zeroclaw_tools/

jira_tool.rs

use async_trait::async_trait;
use reqwest::Client;
use serde_json::{Value, json};
use std::collections::{HashMap, HashSet};
use std::sync::Arc;
use zeroclaw_api::tool::{Tool, ToolResult};
use zeroclaw_config::policy::{SecurityPolicy, ToolOperation};

const JIRA_SEARCH_PAGE_SIZE: u32 = 100;
const MAX_ERROR_BODY_CHARS: usize = 500;

/// Controls how much data is returned by `get_ticket`.
#[derive(Default)]
enum LevelOfDetails {
    Basic,
    #[default]
    BasicSearch,
    Full,
    Changelog,
}

/// Tool for interacting with the Jira REST API.
///
/// When `email` is provided, uses **API v3** with HTTP Basic auth
/// (`email:api_token`) — the standard Jira Cloud authentication model.
///
/// When `email` is `None`, uses **API v2** with Bearer token auth
/// (`Authorization: Bearer <api_token>`) — the standard Jira Server /
/// Data Center (self-hosted) authentication model.
///
/// Supports eight actions gated by `[jira].allowed_actions` in config:
/// - `get_ticket`        — always in the default allowlist; read-only.
/// - `search_tickets`    — requires explicit opt-in; read-only.
/// - `comment_ticket`    — requires explicit opt-in; mutating (Act policy).
/// - `list_projects`     — requires explicit opt-in; read-only.
/// - `myself`            — requires explicit opt-in; read-only. Verifies credentials.
/// - `list_transitions`  — requires explicit opt-in; read-only.
/// - `transition_ticket` — requires explicit opt-in; mutating (Act policy).
/// - `create_ticket`     — requires explicit opt-in; mutating (Act policy).
pub struct JiraTool {
    base_url: String,
    email: Option<String>,
    api_token: String,
    allowed_actions: Vec<String>,
    http: Client,
    security: Arc<SecurityPolicy>,
    timeout_secs: u64,
}

impl JiraTool {
    pub fn new(
        base_url: String,
        email: Option<String>,
        api_token: String,
        allowed_actions: Vec<String>,
        security: Arc<SecurityPolicy>,
        timeout_secs: u64,
    ) -> Self {
        Self {
            base_url: base_url.trim_end_matches('/').to_string(),
            email,
            api_token,
            allowed_actions,
            http: Client::new(),
            security,
            timeout_secs,
        }
    }

    /// `"3"` for Jira Cloud (email present), `"2"` for Server/DC (no email).
    fn api_version(&self) -> &str {
        if self.email.is_some() { "3" } else { "2" }
    }

    /// Returns an authenticated request builder.
    /// Cloud: HTTP Basic (`email:token`). Server/DC: Bearer token.
    fn authenticated(&self, req: reqwest::RequestBuilder) -> reqwest::RequestBuilder {
        match &self.email {
            Some(email) => req.basic_auth(email, Some(&self.api_token)),
            None => req.bearer_auth(&self.api_token),
        }
    }

    /// `true` when connected to Jira Cloud (API v3, email present).
    fn is_cloud(&self) -> bool {
        self.email.is_some()
    }

    fn is_action_allowed(&self, action: &str) -> bool {
        self.allowed_actions.iter().any(|a| a == action)
    }

    async fn get_ticket(
        &self,
        issue_key: &str,
        level: LevelOfDetails,
    ) -> anyhow::Result<ToolResult> {
        validate_issue_key(issue_key)?;
        let ver = self.api_version();
        let url = format!("{}/rest/api/{}/issue/{}", self.base_url, ver, issue_key);

        let query: Vec<(&str, &str)> = match &level {
            LevelOfDetails::Basic => vec![
                ("fields", "summary"),
                ("fields", "priority"),
                ("fields", "status"),
                ("fields", "assignee"),
                ("fields", "description"),
                ("fields", "created"),
                ("fields", "updated"),
                ("fields", "comment"),
                ("expand", "renderedFields"),
            ],
            LevelOfDetails::BasicSearch => vec![
                ("fields", "summary"),
                ("fields", "priority"),
                ("fields", "status"),
                ("fields", "assignee"),
                ("fields", "created"),
                ("fields", "updated"),
            ],
            LevelOfDetails::Full => vec![("expand", "renderedFields"), ("expand", "names")],
            LevelOfDetails::Changelog => vec![("expand", "changelog")],
        };

        let req = self
            .http
            .get(&url)
            .query(&query)
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let resp = self.authenticated(req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira get_ticket request failed"
            );
            anyhow::Error::msg(format!("Jira get_ticket request failed: {e}"))
        })?;

        let status = resp.status();
        if !status.is_success() {
            let text = resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira get_ticket failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        }

        let raw: Value = resp.json().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Failed to parse Jira get_ticket response"
            );
            anyhow::Error::msg(format!("Failed to parse Jira get_ticket response: {e}"))
        })?;

        let shaped = match level {
            LevelOfDetails::Basic => shape_basic(&raw),
            LevelOfDetails::BasicSearch => shape_basic_search(&raw),
            LevelOfDetails::Full => shape_full(&raw),
            LevelOfDetails::Changelog => shape_changelog(&raw),
        };

        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&shaped).unwrap_or_else(|_| shaped.to_string()),
            error: None,
        })
    }

    #[allow(clippy::cast_possible_truncation)]
    async fn search_tickets(
        &self,
        jql: &str,
        max_results: Option<u32>,
    ) -> anyhow::Result<ToolResult> {
        let max_results = max_results.unwrap_or(25).clamp(1, 999);

        let issues = if self.is_cloud() {
            self.search_tickets_v3(jql, max_results).await?
        } else {
            self.search_tickets_v2(jql, max_results).await?
        };

        let output = json!(issues);
        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&output).unwrap_or_else(|_| output.to_string()),
            error: None,
        })
    }

    /// Cloud (v3): `POST /rest/api/3/search/jql` with `nextPageToken` pagination.
    #[allow(clippy::cast_possible_truncation)]
    async fn search_tickets_v3(&self, jql: &str, max_results: u32) -> anyhow::Result<Vec<Value>> {
        let url = format!("{}/rest/api/3/search/jql", self.base_url);
        let mut issues: Vec<Value> = Vec::new();
        let mut next_page_token: Option<String> = None;

        loop {
            let remaining = max_results.saturating_sub(issues.len() as u32);
            let page_size = remaining.min(JIRA_SEARCH_PAGE_SIZE);

            let mut body = json!({
                "jql": jql,
                "maxResults": page_size,
                "fields": ["summary", "priority", "status", "assignee", "created", "updated"]
            });

            if let Some(token) = &next_page_token {
                body["nextPageToken"] = json!(token);
            }

            let req = self
                .http
                .post(&url)
                .json(&body)
                .timeout(std::time::Duration::from_secs(self.timeout_secs));
            let resp = self.authenticated(req).send().await.map_err(|e| {
                ::zeroclaw_log::record!(
                    ERROR,
                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                        .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                        .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                    "jira: Jira search_tickets request failed"
                );
                anyhow::Error::msg(format!("Jira search_tickets request failed: {e}"))
            })?;

            let status = resp.status();
            if !status.is_success() {
                let text = resp.text().await.unwrap_or_default();
                anyhow::bail!(
                    "Jira search_tickets failed ({status}): {}",
                    crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
                );
            }

            let raw: Value = resp.json().await.map_err(|e| {
                ::zeroclaw_log::record!(
                    ERROR,
                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                        .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                        .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                    "jira: Failed to parse Jira search response"
                );
                anyhow::Error::msg(format!("Failed to parse Jira search response: {e}"))
            })?;

            if let Some(page) = raw["issues"].as_array() {
                issues.extend(page.iter().map(shape_basic_search));
            }

            let is_last = raw["isLast"].as_bool().unwrap_or(true);
            if is_last || issues.len() as u32 >= max_results {
                break;
            }

            next_page_token = raw["nextPageToken"].as_str().map(String::from);
            if next_page_token.is_none() {
                break;
            }
        }

        Ok(issues)
    }

    /// Server/DC (v2): `POST /rest/api/2/search` with `startAt` offset pagination.
    #[allow(clippy::cast_possible_truncation)]
    async fn search_tickets_v2(&self, jql: &str, max_results: u32) -> anyhow::Result<Vec<Value>> {
        let url = format!("{}/rest/api/2/search", self.base_url);
        let mut issues: Vec<Value> = Vec::new();
        let mut start_at: u32 = 0;

        loop {
            let remaining = max_results.saturating_sub(issues.len() as u32);
            let page_size = remaining.min(JIRA_SEARCH_PAGE_SIZE);

            let body = json!({
                "jql": jql,
                "startAt": start_at,
                "maxResults": page_size,
                "fields": ["summary", "priority", "status", "assignee", "created", "updated"]
            });

            let req = self
                .http
                .post(&url)
                .json(&body)
                .timeout(std::time::Duration::from_secs(self.timeout_secs));
            let resp = self.authenticated(req).send().await.map_err(|e| {
                ::zeroclaw_log::record!(
                    ERROR,
                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                        .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                        .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                    "jira: Jira search_tickets request failed"
                );
                anyhow::Error::msg(format!("Jira search_tickets request failed: {e}"))
            })?;

            let status = resp.status();
            if !status.is_success() {
                let text = resp.text().await.unwrap_or_default();
                anyhow::bail!(
                    "Jira search_tickets failed ({status}): {}",
                    crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
                );
            }

            let raw: Value = resp.json().await.map_err(|e| {
                ::zeroclaw_log::record!(
                    ERROR,
                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                        .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                        .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                    "jira: Failed to parse Jira search response"
                );
                anyhow::Error::msg(format!("Failed to parse Jira search response: {e}"))
            })?;

            let page = raw["issues"].as_array();
            let page_len = page.map_or(0, |p| p.len());
            if let Some(page) = page {
                issues.extend(page.iter().map(shape_basic_search));
            }

            let total = raw["total"].as_u64().unwrap_or(0) as u32;
            start_at += page_len as u32;
            if page_len == 0 || start_at >= total || issues.len() as u32 >= max_results {
                break;
            }
        }

        Ok(issues)
    }

    async fn comment_ticket(
        &self,
        issue_key: &str,
        comment_text: &str,
    ) -> anyhow::Result<ToolResult> {
        validate_issue_key(issue_key)?;

        let ver = self.api_version();
        let url = format!(
            "{}/rest/api/{}/issue/{}/comment",
            self.base_url, ver, issue_key
        );

        let body = if self.is_cloud() {
            let emails = extract_emails(comment_text);
            let mut mentions: HashMap<String, (String, String)> = HashMap::new();
            for email in emails {
                if let Some(info) = self.resolve_email(&email).await {
                    mentions.insert(email, info);
                }
            }
            let adf = build_adf(comment_text, &mentions);
            json!({ "body": adf })
        } else {
            json!({ "body": comment_text })
        };

        let req = self
            .http
            .post(&url)
            .json(&body)
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let resp = self.authenticated(req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira comment_ticket request failed"
            );
            anyhow::Error::msg(format!("Jira comment_ticket request failed: {e}"))
        })?;

        let status = resp.status();
        if !status.is_success() {
            let text = resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira comment_ticket failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        }

        let response: Value = resp.json().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Failed to parse Jira comment response"
            );
            anyhow::Error::msg(format!("Failed to parse Jira comment response: {e}"))
        })?;

        let shaped = shape_comment_response(&response);
        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&shaped).unwrap_or_else(|_| shaped.to_string()),
            error: None,
        })
    }

    async fn list_projects(&self) -> anyhow::Result<ToolResult> {
        let ver = self.api_version();
        let url = format!("{}/rest/api/{}/project", self.base_url, ver);

        let req = self
            .http
            .get(&url)
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let resp = self.authenticated(req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira list_projects request failed"
            );
            anyhow::Error::msg(format!("Jira list_projects request failed: {e}"))
        })?;

        let status = resp.status();
        if !status.is_success() {
            let text = resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira list_projects failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        }

        let projects: Vec<Value> = resp.json().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Failed to parse Jira list_projects response"
            );
            anyhow::Error::msg(format!("Failed to parse Jira list_projects response: {e}"))
        })?;

        let keys: Vec<String> = projects
            .iter()
            .filter_map(|p| p["key"].as_str().map(String::from))
            .collect();

        const STATUS_CONCURRENCY: usize = 5;

        let users_url = format!(
            "{}/rest/api/{}/user/assignable/multiProjectSearch",
            self.base_url, ver
        );

        let users_req = self
            .http
            .get(&users_url)
            .query(&[
                ("projectKeys", keys.join(",").as_str()),
                ("maxResults", "50"),
            ])
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let users_resp = self.authenticated(users_req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira list_projects users request failed"
            );
            anyhow::Error::msg(format!("Jira list_projects users request failed: {e}"))
        })?;

        let users: Vec<Value> = if users_resp.status().is_success() {
            users_resp.json().await.map_err(|e| {
                ::zeroclaw_log::record!(
                    ERROR,
                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                        .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                        .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                    "jira: Failed to parse Jira list_projects users response"
                );
                anyhow::Error::msg(format!(
                    "Failed to parse Jira list_projects users response: {e}"
                ))
            })?
        } else {
            let status = users_resp.status();
            let text = users_resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira list_projects users failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        };

        let mut set: tokio::task::JoinSet<(usize, anyhow::Result<Value>)> =
            tokio::task::JoinSet::new();
        let mut statuses_results = vec![json!([]); keys.len()];

        for (i, key) in keys.iter().enumerate() {
            if set.len() >= STATUS_CONCURRENCY {
                let Some(Ok((idx, result))) = set.join_next().await else {
                    continue;
                };
                statuses_results[idx] = result.map_err(|e| {
                    ::zeroclaw_log::record!(
                        ERROR,
                        ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                            .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                            .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                        "jira: Jira statuses failed"
                    );
                    anyhow::Error::msg(format!("Jira statuses failed: {e}"))
                })?;
            }

            let client = self.http.clone();
            let request_url = format!("{url}/{key}/statuses");
            let email = self.email.clone();
            let token = self.api_token.clone();
            let timeout = self.timeout_secs;

            set.spawn(async move {
                let result = async {
                    let req = client
                        .get(&request_url)
                        .timeout(std::time::Duration::from_secs(timeout));
                    let req = match &email {
                        Some(e) => req.basic_auth(e, Some(&token)),
                        None => req.bearer_auth(&token),
                    };
                    let resp = req.send().await.map_err(|e| {
                        ::zeroclaw_log::record!(
                            ERROR,
                            ::zeroclaw_log::Event::new(
                                module_path!(),
                                ::zeroclaw_log::Action::Fail
                            )
                            .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                            .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                            "jira: statuses request failed"
                        );
                        anyhow::Error::msg(format!("statuses request failed: {e}"))
                    })?;

                    if !resp.status().is_success() {
                        anyhow::bail!("statuses request returned {}", resp.status());
                    }

                    resp.json::<Value>().await.map_err(|e| {
                        ::zeroclaw_log::record!(
                            ERROR,
                            ::zeroclaw_log::Event::new(
                                module_path!(),
                                ::zeroclaw_log::Action::Fail
                            )
                            .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                            .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                            "jira: failed to parse statuses response"
                        );
                        anyhow::Error::msg(format!("failed to parse statuses response: {e}"))
                    })
                }
                .await;
                (i, result)
            });
        }

        while let Some(Ok((idx, result))) = set.join_next().await {
            statuses_results[idx] = result.map_err(|e| {
                ::zeroclaw_log::record!(
                    ERROR,
                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                        .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                        .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                    "jira: Jira statuses failed"
                );
                anyhow::Error::msg(format!("Jira statuses failed: {e}"))
            })?;
        }

        let shaped_projects = shape_projects(&projects, &statuses_results);
        let shaped_users: Vec<Value> = users
            .iter()
            .filter_map(|u| {
                let display = u["displayName"].as_str()?;
                let email = u["emailAddress"].as_str()?;
                Some(json!({ "displayName": display, "emailAddress": email }))
            })
            .collect();

        let output = json!({ "projects": shaped_projects, "users": shaped_users });
        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&output).unwrap_or_else(|_| output.to_string()),
            error: None,
        })
    }

    async fn get_myself(&self) -> anyhow::Result<ToolResult> {
        let ver = self.api_version();
        let url = format!("{}/rest/api/{}/myself", self.base_url, ver);

        let req = self
            .http
            .get(&url)
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let resp = self.authenticated(req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira myself request failed"
            );
            anyhow::Error::msg(format!("Jira myself request failed: {e}"))
        })?;

        let status = resp.status();
        if !status.is_success() {
            let text = resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira myself failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        }

        let raw: Value = resp.json().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Failed to parse Jira myself response"
            );
            anyhow::Error::msg(format!("Failed to parse Jira myself response: {e}"))
        })?;

        let shaped = json!({
            "accountId":    raw["accountId"],
            "displayName":  raw["displayName"],
            "emailAddress": raw["emailAddress"],
            "active":       raw["active"],
        });

        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&shaped).unwrap_or_else(|_| shaped.to_string()),
            error: None,
        })
    }

    async fn resolve_email(&self, email: &str) -> Option<(String, String)> {
        let ver = self.api_version();
        let url = format!("{}/rest/api/{}/user/search", self.base_url, ver);
        let req = self
            .http
            .get(&url)
            .query(&[("query", email)])
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let result = self
            .authenticated(req)
            .send()
            .await
            .ok()?
            .json::<Value>()
            .await
            .ok()?;

        result.as_array()?.iter().find_map(|u| {
            let account_email = u["emailAddress"].as_str()?;
            if account_email.eq_ignore_ascii_case(email) {
                Some((
                    u["accountId"].as_str()?.to_string(),
                    u["displayName"].as_str()?.to_string(),
                ))
            } else {
                None
            }
        })
    }

    /// Fetches the available transitions for an issue and returns a minimal
    /// shape `{ transitions: [{ id, name, to_status }] }`.
    async fn fetch_transitions(&self, issue_key: &str) -> anyhow::Result<Vec<Value>> {
        validate_issue_key(issue_key)?;
        let ver = self.api_version();
        let url = format!(
            "{}/rest/api/{}/issue/{}/transitions",
            self.base_url, ver, issue_key
        );

        let req = self
            .http
            .get(&url)
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let resp = self.authenticated(req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira list_transitions request failed"
            );
            anyhow::Error::msg(format!("Jira list_transitions request failed: {e}"))
        })?;

        let status = resp.status();
        if !status.is_success() {
            let text = resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira list_transitions failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        }

        let raw: Value = resp.json().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Failed to parse Jira transitions response"
            );
            anyhow::Error::msg(format!("Failed to parse Jira transitions response: {e}"))
        })?;

        Ok(shape_transitions(&raw))
    }

    async fn list_transitions(&self, issue_key: &str) -> anyhow::Result<ToolResult> {
        let transitions = self.fetch_transitions(issue_key).await?;
        let output = json!({ "transitions": transitions });
        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&output).unwrap_or_else(|_| output.to_string()),
            error: None,
        })
    }

    async fn transition_ticket(
        &self,
        issue_key: &str,
        transition_id: Option<&str>,
        transition_name: Option<&str>,
    ) -> anyhow::Result<ToolResult> {
        validate_issue_key(issue_key)?;

        // Resolve transition_name → id if needed.
        let resolved_id: String = match (transition_id, transition_name) {
            (Some(id), _) if !id.trim().is_empty() => id.to_string(),
            (_, Some(name)) if !name.trim().is_empty() => {
                let transitions = self.fetch_transitions(issue_key).await?;
                let needle = name.trim().to_ascii_lowercase();
                let found = transitions.iter().find_map(|t| {
                    let n = t["name"].as_str()?;
                    if n.eq_ignore_ascii_case(&needle) || n.to_ascii_lowercase() == needle {
                        t["id"].as_str().map(String::from)
                    } else {
                        None
                    }
                });
                match found {
                    Some(id) => id,
                    None => {
                        let available: Vec<&str> = transitions
                            .iter()
                            .filter_map(|t| t["name"].as_str())
                            .collect();
                        anyhow::bail!(
                            "Transition '{name}' not found for {issue_key}. Available: {}",
                            available.join(", ")
                        );
                    }
                }
            }
            _ => {
                anyhow::bail!(
                    "transition_ticket requires exactly one of transition_id or transition_name"
                );
            }
        };

        let ver = self.api_version();
        let url = format!(
            "{}/rest/api/{}/issue/{}/transitions",
            self.base_url, ver, issue_key
        );
        let body = json!({ "transition": { "id": resolved_id } });

        let req = self
            .http
            .post(&url)
            .json(&body)
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let resp = self.authenticated(req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira transition_ticket request failed"
            );
            anyhow::Error::msg(format!("Jira transition_ticket request failed: {e}"))
        })?;

        let status = resp.status();
        if !status.is_success() {
            let text = resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira transition_ticket failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        }

        // Jira returns 204 No Content on a successful transition.
        let output = json!({
            "ok": true,
            "issue_key": issue_key,
            "transition_id": resolved_id,
        });
        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&output).unwrap_or_else(|_| output.to_string()),
            error: None,
        })
    }

    #[allow(clippy::too_many_arguments)]
    async fn create_ticket(
        &self,
        project_key: &str,
        issue_type: &str,
        summary: &str,
        description: Option<&str>,
        assignee: Option<&str>,
        labels: Option<&[String]>,
        parent_key: Option<&str>,
    ) -> anyhow::Result<ToolResult> {
        validate_project_key(project_key)?;
        if summary.trim().is_empty() {
            anyhow::bail!("create_ticket requires a non-empty summary");
        }
        if issue_type.trim().is_empty() {
            anyhow::bail!("create_ticket requires a non-empty issue_type");
        }
        if let Some(parent) = parent_key {
            validate_issue_key(parent)?;
        }

        let mut fields = serde_json::Map::new();
        fields.insert("project".into(), json!({ "key": project_key }));
        fields.insert("issuetype".into(), json!({ "name": issue_type }));
        fields.insert("summary".into(), json!(summary));

        if let Some(desc) = description {
            let value = if self.is_cloud() {
                build_adf(desc, &HashMap::new())
            } else {
                json!(desc)
            };
            fields.insert("description".into(), value);
        }

        if let Some(a) = assignee {
            let value = if self.is_cloud() {
                json!({ "accountId": a })
            } else {
                json!({ "name": a })
            };
            fields.insert("assignee".into(), value);
        }

        if let Some(ls) = labels {
            fields.insert("labels".into(), json!(ls));
        }

        if let Some(parent) = parent_key {
            fields.insert("parent".into(), json!({ "key": parent }));
        }

        let body = json!({ "fields": Value::Object(fields) });

        let ver = self.api_version();
        let url = format!("{}/rest/api/{}/issue", self.base_url, ver);

        let req = self
            .http
            .post(&url)
            .json(&body)
            .timeout(std::time::Duration::from_secs(self.timeout_secs));
        let resp = self.authenticated(req).send().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Jira create_ticket request failed"
            );
            anyhow::Error::msg(format!("Jira create_ticket request failed: {e}"))
        })?;

        let status = resp.status();
        if !status.is_success() {
            let text = resp.text().await.unwrap_or_default();
            anyhow::bail!(
                "Jira create_ticket failed ({status}): {}",
                crate::util_helpers::truncate_with_ellipsis(&text, MAX_ERROR_BODY_CHARS)
            );
        }

        let raw: Value = resp.json().await.map_err(|e| {
            ::zeroclaw_log::record!(
                ERROR,
                ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                    .with_outcome(::zeroclaw_log::EventOutcome::Failure)
                    .with_attrs(::serde_json::json!({"error": format!("{}", e)})),
                "jira: Failed to parse Jira create_ticket response"
            );
            anyhow::Error::msg(format!("Failed to parse Jira create_ticket response: {e}"))
        })?;

        let key = raw["key"].as_str().unwrap_or("");
        let output = json!({
            "id":         raw["id"],
            "key":        key,
            "self_url":   raw["self"],
            "browse_url": format!("{}/browse/{}", self.base_url, key),
        });
        Ok(ToolResult {
            success: true,
            output: serde_json::to_string_pretty(&output).unwrap_or_else(|_| output.to_string()),
            error: None,
        })
    }
}

#[async_trait]
impl Tool for JiraTool {
    fn name(&self) -> &str {
        "jira"
    }

    fn description(&self) -> &str {
        "Interact with Jira: read tickets, search with JQL, add comments, list projects and per-issue transitions, transition an issue through its workflow, and create new issues."
    }

    fn parameters_schema(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": {
                "action": {
                    "type": "string",
                    "enum": [
                        "get_ticket",
                        "search_tickets",
                        "comment_ticket",
                        "list_projects",
                        "myself",
                        "list_transitions",
                        "transition_ticket",
                        "create_ticket"
                    ],
                    "description": "The Jira action to perform. Enabled actions are configured in [jira].allowed_actions. Use 'myself' to verify that credentials are valid and the Jira connection is working."
                },
                "issue_key": {
                    "type": "string",
                    "description": "Jira issue key, e.g. 'PROJ-123'. Required for get_ticket, comment_ticket, list_transitions, and transition_ticket."
                },
                "level_of_details": {
                    "type": "string",
                    "enum": ["basic", "basic_search", "full", "changelog"],
                    "description": "How much data to return for get_ticket. Omit to use the default ('basic'). Options: 'basic' — summary, status, priority, assignee, rendered description, and rendered comments (best for reading a ticket in full); 'basic_search' — lightweight fields only, no description or comments (best when you only need to identify the ticket); 'full' — all Jira fields plus rendered HTML (verbose, use sparingly); 'changelog' — issue key and full change history only."
                },
                "jql": {
                    "type": "string",
                    "description": "JQL query string for search_tickets. Example: 'project = PROJ AND status = \"In Progress\" ORDER BY updated DESC'."
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum number of issues to return for search_tickets. Defaults to 25, capped at 999.",
                    "default": 25
                },
                "comment": {
                    "type": "string",
                    "description": "Comment body for comment_ticket. In Jira Cloud mode, supports a limited markdown-like syntax converted to Atlassian Document Format (ADF): mention a user with @user@domain.com (the leading @ is required; a bare email without @ prefix is treated as plain text), bold with **text**, bullet list items with a leading '- ', and newlines as line breaks. In Jira Server/Data Center mode, comments are posted as plain text with no ADF conversion or mention resolution. Example: 'Hi @john@company.com, this is **important**.\n- Check the logs\n- Rerun the pipeline'"
                },
                "transition_id": {
                    "type": "string",
                    "description": "Transition ID to apply for transition_ticket. Provide either transition_id or transition_name (not both). Use list_transitions to discover the IDs valid for an issue's current state."
                },
                "transition_name": {
                    "type": "string",
                    "description": "Transition name (case-insensitive) to apply for transition_ticket, e.g. 'In Progress' or 'Done'. Provide either transition_id or transition_name (not both). The tool resolves the name against the issue's available transitions and returns an error listing valid names if not found."
                },
                "project_key": {
                    "type": "string",
                    "description": "Jira project key, e.g. 'PROJ'. Required for create_ticket. Use list_projects to discover keys."
                },
                "issue_type": {
                    "type": "string",
                    "description": "Issue type name, e.g. 'Task', 'Bug', 'Story'. Required for create_ticket. Valid values per project are returned by list_projects."
                },
                "summary": {
                    "type": "string",
                    "description": "Ticket title. Required for create_ticket. Must be non-empty."
                },
                "description": {
                    "type": "string",
                    "description": "Ticket description for create_ticket. Optional. In Jira Cloud mode, the same limited markdown-like syntax as 'comment' is supported and rendered to ADF (no mention resolution). In Server/Data Center mode, sent as plain text."
                },
                "assignee": {
                    "type": "string",
                    "description": "Assignee for create_ticket. Optional. In Jira Cloud, pass an accountId; in Server/Data Center, pass a username."
                },
                "labels": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Labels to attach to the new issue for create_ticket. Optional."
                },
                "parent_key": {
                    "type": "string",
                    "description": "Parent issue key for create_ticket. Optional. Used for sub-tasks or to set the parent epic (e.g. 'PROJ-100')."
                }
            },
            "required": ["action"]
        })
    }

    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
        let action = match args.get("action").and_then(|v| v.as_str()) {
            Some(a) => a,
            None => {
                return Ok(ToolResult {
                    success: false,
                    output: String::new(),
                    error: Some("Missing required parameter: action".into()),
                });
            }
        };

        // Reject unknown actions before the allowlist check so typos produce a
        // clear "unknown action" error rather than a misleading "not enabled" one.
        if !matches!(
            action,
            "get_ticket"
                | "search_tickets"
                | "comment_ticket"
                | "list_projects"
                | "myself"
                | "list_transitions"
                | "transition_ticket"
                | "create_ticket"
        ) {
            return Ok(ToolResult {
                success: false,
                output: String::new(),
                error: Some(format!(
                    "Unknown action: '{action}'. Valid actions: get_ticket, search_tickets, comment_ticket, list_projects, myself, list_transitions, transition_ticket, create_ticket"
                )),
            });
        }

        if !self.is_action_allowed(action) {
            return Ok(ToolResult {
                success: false,
                output: String::new(),
                error: Some(format!(
                    "Action '{action}' is not enabled. Add it to jira.allowed_actions in config.toml. \
                     Currently allowed: {}",
                    self.allowed_actions.join(", ")
                )),
            });
        }

        let operation = match action {
            "get_ticket" | "search_tickets" | "list_projects" | "myself" | "list_transitions" => {
                ToolOperation::Read
            }
            "comment_ticket" | "transition_ticket" | "create_ticket" => ToolOperation::Act,
            _ => unreachable!(),
        };

        if let Err(error) = self.security.enforce_tool_operation(operation, "jira") {
            return Ok(ToolResult {
                success: false,
                output: String::new(),
                error: Some(error),
            });
        }

        let result = match action {
            "get_ticket" => {
                let issue_key = match args.get("issue_key").and_then(|v| v.as_str()) {
                    Some(k) => k,
                    None => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some("get_ticket requires issue_key parameter".into()),
                        });
                    }
                };
                let level = match args.get("level_of_details").and_then(|v| v.as_str()) {
                    Some("basic_search") => LevelOfDetails::BasicSearch,
                    Some("full") => LevelOfDetails::Full,
                    Some("changelog") => LevelOfDetails::Changelog,
                    _ => LevelOfDetails::Basic,
                };
                self.get_ticket(issue_key, level).await
            }
            "search_tickets" => {
                let jql = match args.get("jql").and_then(|v| v.as_str()) {
                    Some(j) => j,
                    None => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some("search_tickets requires jql parameter".into()),
                        });
                    }
                };
                let max_results = args
                    .get("max_results")
                    .and_then(|v| v.as_u64())
                    .map(|n| u32::try_from(n).unwrap_or(u32::MAX));
                self.search_tickets(jql, max_results).await
            }
            "myself" => self.get_myself().await,
            "list_projects" => self.list_projects().await,
            "comment_ticket" => {
                let issue_key = match args.get("issue_key").and_then(|v| v.as_str()) {
                    Some(k) => k,
                    None => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some("comment_ticket requires issue_key parameter".into()),
                        });
                    }
                };
                let comment = match args.get("comment").and_then(|v| v.as_str()) {
                    Some(c) if !c.trim().is_empty() => c,
                    _ => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some(
                                "comment_ticket requires a non-empty comment parameter".into(),
                            ),
                        });
                    }
                };
                self.comment_ticket(issue_key, comment).await
            }
            "list_transitions" => {
                let issue_key = match args.get("issue_key").and_then(|v| v.as_str()) {
                    Some(k) => k,
                    None => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some("list_transitions requires issue_key parameter".into()),
                        });
                    }
                };
                self.list_transitions(issue_key).await
            }
            "transition_ticket" => {
                let issue_key = match args.get("issue_key").and_then(|v| v.as_str()) {
                    Some(k) => k,
                    None => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some("transition_ticket requires issue_key parameter".into()),
                        });
                    }
                };
                let transition_id = args
                    .get("transition_id")
                    .and_then(|v| v.as_str())
                    .filter(|s| !s.trim().is_empty());
                let transition_name = args
                    .get("transition_name")
                    .and_then(|v| v.as_str())
                    .filter(|s| !s.trim().is_empty());
                if transition_id.is_none() && transition_name.is_none() {
                    return Ok(ToolResult {
                        success: false,
                        output: String::new(),
                        error: Some(
                            "transition_ticket requires either transition_id or transition_name"
                                .into(),
                        ),
                    });
                }
                if transition_id.is_some() && transition_name.is_some() {
                    return Ok(ToolResult {
                        success: false,
                        output: String::new(),
                        error: Some(
                            "transition_ticket accepts only one of transition_id or transition_name, not both".into(),
                        ),
                    });
                }
                self.transition_ticket(issue_key, transition_id, transition_name)
                    .await
            }
            "create_ticket" => {
                let project_key = match args.get("project_key").and_then(|v| v.as_str()) {
                    Some(k) if !k.trim().is_empty() => k,
                    _ => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some(
                                "create_ticket requires a non-empty project_key parameter".into(),
                            ),
                        });
                    }
                };
                let issue_type = match args.get("issue_type").and_then(|v| v.as_str()) {
                    Some(t) if !t.trim().is_empty() => t,
                    _ => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some(
                                "create_ticket requires a non-empty issue_type parameter".into(),
                            ),
                        });
                    }
                };
                let summary = match args.get("summary").and_then(|v| v.as_str()) {
                    Some(s) if !s.trim().is_empty() => s,
                    _ => {
                        return Ok(ToolResult {
                            success: false,
                            output: String::new(),
                            error: Some(
                                "create_ticket requires a non-empty summary parameter".into(),
                            ),
                        });
                    }
                };
                let description = args
                    .get("description")
                    .and_then(|v| v.as_str())
                    .filter(|s| !s.is_empty());
                let assignee = args
                    .get("assignee")
                    .and_then(|v| v.as_str())
                    .filter(|s| !s.trim().is_empty());
                let labels: Option<Vec<String>> = args.get("labels").and_then(|v| {
                    v.as_array().map(|arr| {
                        arr.iter()
                            .filter_map(|x| x.as_str().map(String::from))
                            .collect()
                    })
                });
                let parent_key = args
                    .get("parent_key")
                    .and_then(|v| v.as_str())
                    .filter(|s| !s.trim().is_empty());
                self.create_ticket(
                    project_key,
                    issue_type,
                    summary,
                    description,
                    assignee,
                    labels.as_deref(),
                    parent_key,
                )
                .await
            }
            _ => unreachable!(),
        };

        match result {
            Ok(tool_result) => Ok(tool_result),
            Err(e) => Ok(ToolResult {
                success: false,
                output: String::new(),
                error: Some(e.to_string()),
            }),
        }
    }
}

// ── Input validation ──────────────────────────────────────────────────────────

/// Validates that `issue_key` matches the Jira key format `PROJ-123` or `proj-123`.
/// Prevents path traversal if a crafted key like `../../other` were interpolated
/// directly into the URL.
fn validate_issue_key(key: &str) -> anyhow::Result<()> {
    let valid = key.split_once('-').is_some_and(|(project, number)| {
        !project.is_empty()
            && project.chars().all(|c| c.is_ascii_alphanumeric())
            && !number.is_empty()
            && number.chars().all(|c| c.is_ascii_digit())
    });
    if valid {
        Ok(())
    } else {
        anyhow::bail!(
            "Invalid issue key '{key}'. Expected format: PROJECT-123 (e.g. PROJ-42, proj-42)"
        )
    }
}

/// Validates that `key` matches the Jira project key format. Same character
/// class as the project portion of `validate_issue_key` so the two stay in
/// step.
fn validate_project_key(key: &str) -> anyhow::Result<()> {
    let valid = !key.is_empty() && key.chars().all(|c| c.is_ascii_alphanumeric());
    if valid {
        Ok(())
    } else {
        anyhow::bail!("Invalid project key '{key}'. Expected ASCII alphanumeric, e.g. PROJ")
    }
}

// ── Response shaping ──────────────────────────────────────────────────────────

/// Safely extracts the first 10 characters (date prefix) from a string.
/// Returns the full string if it is shorter than 10 characters instead of
/// panicking on out-of-bounds slice indexing.
fn date_prefix(s: &str) -> &str {
    s.get(..10).unwrap_or(s)
}

fn shape_basic(raw: &Value) -> Value {
    let f = &raw["fields"];
    let rf = &raw["renderedFields"];

    // Build a lookup map from comment ID → rendered body for O(1) access
    // instead of scanning the rendered array for each comment (O(n²)).
    let rendered_by_id: HashMap<&str, &str> = rf["comment"]["comments"]
        .as_array()
        .map(|arr| {
            arr.iter()
                .filter_map(|rc| Some((rc["id"].as_str()?, rc["body"].as_str()?)))
                .collect()
        })
        .unwrap_or_default();

    let comments: Vec<Value> = f["comment"]["comments"]
        .as_array()
        .map(|arr| {
            arr.iter()
                .map(|c| {
                    let id = c["id"].as_str().unwrap_or("");
                    json!({
                        "author": c["author"]["displayName"],
                        "created": date_prefix(c["created"].as_str().unwrap_or("")),
                        "body": rendered_by_id.get(id).copied().unwrap_or("")
                    })
                })
                .collect()
        })
        .unwrap_or_default();

    json!({
        "key":         raw["key"],
        "summary":     f["summary"],
        "status":      f["status"]["name"],
        "priority":    f["priority"]["name"],
        "assignee":    f["assignee"]["displayName"],
        "created":     date_prefix(f["created"].as_str().unwrap_or("")),
        "updated":     date_prefix(f["updated"].as_str().unwrap_or("")),
        "description": rf["description"].as_str().unwrap_or(""),
        "comments":    comments,
    })
}

fn shape_basic_search(raw: &Value) -> Value {
    let f = &raw["fields"];
    json!({
        "key":      raw["key"],
        "summary":  f["summary"],
        "status":   f["status"]["name"],
        "priority": f["priority"]["name"],
        "assignee": f["assignee"]["displayName"],
        "created":  date_prefix(f["created"].as_str().unwrap_or("")),
        "updated":  date_prefix(f["updated"].as_str().unwrap_or("")),
    })
}

fn shape_full(raw: &Value) -> Value {
    let mut result = raw.clone();
    let rf = &raw["renderedFields"];

    if let Some(desc) = rf["description"].as_str() {
        result["fields"]["description"] = json!(desc);
    }

    if let (Some(comments), Some(rendered_comments)) = (
        result["fields"]["comment"]["comments"].as_array_mut(),
        rf["comment"]["comments"].as_array(),
    ) {
        for (c, rc) in comments.iter_mut().zip(rendered_comments.iter()) {
            if let Some(body) = rc["body"].as_str() {
                c["body"] = json!(body);
            }
        }
    }

    result.as_object_mut().unwrap().remove("renderedFields");
    result
}

fn shape_changelog(raw: &Value) -> Value {
    json!({
        "key":       raw["key"],
        "changelog": raw["changelog"],
    })
}

/// Returns only the comment ID, author, and creation date — avoids
/// exposing internal Jira metadata back to the AI.
fn shape_comment_response(raw: &Value) -> Value {
    json!({
        "id":      raw["id"],
        "author":  raw["author"]["displayName"],
        "created": date_prefix(raw["created"].as_str().unwrap_or("")),
    })
}

/// Trims Jira's transitions response to `[{ id, name, to_status }]`, dropping
/// icons, conditions, and other workflow-engine internals.
fn shape_transitions(raw: &Value) -> Vec<Value> {
    raw["transitions"]
        .as_array()
        .map(|arr| {
            arr.iter()
                .map(|t| {
                    json!({
                        "id":        t["id"],
                        "name":      t["name"],
                        "to_status": t["to"]["name"],
                    })
                })
                .collect()
        })
        .unwrap_or_default()
}

fn shape_projects(projects: &[Value], statuses_per_project: &[Value]) -> Vec<Value> {
    projects
        .iter()
        .zip(statuses_per_project.iter())
        .map(|(p, statuses)| {
            let mut issue_types: Vec<String> = Vec::new();
            let mut all_statuses: HashSet<String> = HashSet::new();

            if let Some(arr) = statuses.as_array() {
                for it in arr {
                    if let Some(name) = it["name"].as_str() {
                        issue_types.push(name.to_string());
                    }
                    if let Some(ss) = it["statuses"].as_array() {
                        for s in ss {
                            if let Some(sn) = s["name"].as_str() {
                                all_statuses.insert(sn.to_string());
                            }
                        }
                    }
                }
            }

            let mut ordered: Vec<String> = all_statuses.into_iter().collect();
            ordered.sort();

            json!({
                "key":         p["key"],
                "name":        p["name"],
                "projectType": p["projectTypeKey"],
                "style":       p["style"],
                "issueTypes":  issue_types,
                "statuses":    ordered,
            })
        })
        .collect()
}

// ── Comment / ADF builder ─────────────────────────────────────────────────────

/// Strips trailing punctuation that commonly appears after an email address
/// (e.g. `@john@co.com,` or `@john@co.com)`). Also strips leading bracket-like
/// punctuation so `@(john@co.com)` resolves correctly.
fn clean_email(s: &str) -> &str {
    s.trim_start_matches(['(', '['])
        .trim_end_matches([',', '!', '?', ':', ';', ')', ']'])
}

fn extract_emails(text: &str) -> Vec<String> {
    let mut emails = Vec::new();
    for word in text.split_whitespace() {
        if let Some(rest) = word.strip_prefix('@') {
            let email = clean_email(rest);
            if email.contains('@') {
                emails.push(email.to_string());
            }
        }
    }
    let mut seen = std::collections::HashSet::new();
    emails.retain(|e| seen.insert(e.clone()));
    emails
}

fn parse_inline(text: &str, mentions: &HashMap<String, (String, String)>) -> Vec<Value> {
    let mut nodes: Vec<Value> = Vec::new();
    let mut chars = text.chars().peekable();
    let mut current = String::new();

    while let Some(ch) = chars.next() {
        if ch == '*' && chars.peek() == Some(&'*') {
            chars.next(); // consume second *
            if !current.is_empty() {
                nodes.push(json!({ "type": "text", "text": current.clone() }));
                current.clear();
            }
            let mut bold = String::new();
            let mut closed = false;
            loop {
                match chars.next() {
                    Some('*') if chars.peek() == Some(&'*') => {
                        chars.next(); // consume second *
                        closed = true;
                        break;
                    }
                    Some(c) => bold.push(c),
                    None => break,
                }
            }
            if closed && !bold.is_empty() {
                nodes.push(json!({
                    "type": "text",
                    "text": bold,
                    "marks": [{ "type": "strong" }]
                }));
            } else if !bold.is_empty() {
                // Unmatched ** — emit as literal text
                current.push_str("**");
                current.push_str(&bold);
            }
        } else if ch == '@' {
            let mut raw = String::new();
            while let Some(&next) = chars.peek() {
                if next.is_whitespace() {
                    break;
                }
                raw.push(chars.next().unwrap());
            }
            let email = clean_email(&raw);
            // Compute the end position of `email` within `raw` via pointer
            // arithmetic so the suffix is correct even when leading chars were
            // stripped by clean_email.
            let email_end = (email.as_ptr() as usize - raw.as_ptr() as usize) + email.len();
            let suffix = &raw[email_end..];
            if email.contains('@') {
                if let Some((account_id, display_name)) = mentions.get(email) {
                    if !current.is_empty() {
                        nodes.push(json!({ "type": "text", "text": current.clone() }));
                        current.clear();
                    }
                    nodes.push(json!({
                        "type": "mention",
                        "attrs": {
                            "id": account_id,
                            "text": format!("@{}", display_name)
                        }
                    }));
                    if !suffix.is_empty() {
                        current.push_str(suffix);
                    }
                } else {
                    current.push('@');
                    current.push_str(&raw);
                }
            } else {
                current.push('@');
                current.push_str(email);
            }
        } else {
            current.push(ch);
        }
    }

    if !current.is_empty() {
        nodes.push(json!({ "type": "text", "text": current }));
    }

    nodes
}

fn build_adf(text: &str, mentions: &HashMap<String, (String, String)>) -> Value {
    let mut content: Vec<Value> = Vec::new();
    let mut paragraph: Vec<Value> = Vec::new();
    let mut list_items: Vec<Value> = Vec::new();

    let flush_paragraph = |paragraph: &mut Vec<Value>, content: &mut Vec<Value>| {
        if !paragraph.is_empty() {
            content.push(json!({ "type": "paragraph", "content": paragraph.clone() }));
            paragraph.clear();
        }
    };

    let flush_list = |list_items: &mut Vec<Value>, content: &mut Vec<Value>| {
        if !list_items.is_empty() {
            content.push(json!({ "type": "bulletList", "content": list_items.clone() }));
            list_items.clear();
        }
    };

    for line in text.lines() {
        if line.trim().is_empty() {
            flush_paragraph(&mut paragraph, &mut content);
            flush_list(&mut list_items, &mut content);
        } else if let Some(item) = line.strip_prefix("- ") {
            flush_paragraph(&mut paragraph, &mut content);
            let inline = parse_inline(item, mentions);
            list_items.push(json!({
                "type": "listItem",
                "content": [{ "type": "paragraph", "content": inline }]
            }));
        } else {
            flush_list(&mut list_items, &mut content);
            if !paragraph.is_empty() {
                paragraph.push(json!({ "type": "hardBreak" }));
            }
            paragraph.extend(parse_inline(line, mentions));
        }
    }

    flush_paragraph(&mut paragraph, &mut content);
    flush_list(&mut list_items, &mut content);

    json!({ "type": "doc", "version": 1, "content": content })
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use zeroclaw_config::autonomy::AutonomyLevel;
    use zeroclaw_config::policy::SecurityPolicy;

    fn test_security() -> Arc<SecurityPolicy> {
        Arc::new(SecurityPolicy {
            autonomy: AutonomyLevel::Supervised,
            ..SecurityPolicy::default()
        })
    }

    fn test_tool_with_base_url(
        base_url: String,
        email: Option<String>,
        api_token: &str,
        allowed_actions: Vec<&str>,
    ) -> JiraTool {
        JiraTool::new(
            base_url,
            email,
            api_token.into(),
            allowed_actions.into_iter().map(String::from).collect(),
            test_security(),
            30,
        )
    }

    /// Cloud mode helper (email present → API v3 + Basic auth).
    fn test_tool(allowed_actions: Vec<&str>) -> JiraTool {
        test_tool_with_base_url(
            "https://test.atlassian.net".into(),
            Some("test@example.com".into()),
            "test-token",
            allowed_actions,
        )
    }

    /// Server/DC mode helper (no email → API v2 + Bearer auth).
    fn test_tool_server(allowed_actions: Vec<&str>) -> JiraTool {
        test_tool_with_base_url(
            "https://internal-jira.company.com".into(),
            None,
            "pat-token-abc",
            allowed_actions,
        )
    }

    fn basic_auth_header(email: &str, token: &str) -> String {
        use base64::Engine as _;

        let encoded = base64::engine::general_purpose::STANDARD.encode(format!("{email}:{token}"));
        format!("Basic {encoded}")
    }

    fn basic_search_issue(key: &str) -> Value {
        json!({
            "key": key,
            "fields": {
                "summary": "Fix bug",
                "status": { "name": "In Progress" },
                "priority": { "name": "High" },
                "assignee": { "displayName": "Jane" },
                "created": "2024-01-15T10:00:00.000Z",
                "updated": "2024-03-01T12:00:00.000Z"
            }
        })
    }

    // ── API version / auth mode tests ───────────────────────────────────────

    #[test]
    fn cloud_tool_uses_api_v3() {
        let tool = test_tool(vec!["get_ticket"]);
        assert_eq!(tool.api_version(), "3");
        assert!(tool.is_cloud());
    }

    #[test]
    fn server_tool_uses_api_v2() {
        let tool = test_tool_server(vec!["get_ticket"]);
        assert_eq!(tool.api_version(), "2");
        assert!(!tool.is_cloud());
    }

    #[test]
    fn tool_name_is_jira() {
        assert_eq!(test_tool(vec!["get_ticket"]).name(), "jira");
    }

    // ── Request shape tests ─────────────────────────────────────────────────

    #[tokio::test]
    async fn cloud_search_uses_basic_auth_v3_endpoint_and_next_page_token() {
        use wiremock::matchers::{body_json, header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let auth = basic_auth_header("test@example.com", "test-token");
        let fields = json!([
            "summary", "priority", "status", "assignee", "created", "updated"
        ]);

        let first_body = json!({
            "jql": "project = PROJ",
            "maxResults": 2,
            "fields": fields
        });
        Mock::given(method("POST"))
            .and(path("/rest/api/3/search/jql"))
            .and(header("authorization", auth.as_str()))
            .and(body_json(&first_body))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "issues": [basic_search_issue("PROJ-1")],
                "isLast": false,
                "nextPageToken": "page-2"
            })))
            .expect(1)
            .mount(&server)
            .await;

        let second_body = json!({
            "jql": "project = PROJ",
            "maxResults": 1,
            "fields": fields,
            "nextPageToken": "page-2"
        });
        Mock::given(method("POST"))
            .and(path("/rest/api/3/search/jql"))
            .and(header("authorization", auth.as_str()))
            .and(body_json(&second_body))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "issues": [basic_search_issue("PROJ-2")],
                "isLast": true
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["search_tickets"],
        );
        let result = tool
            .execute(json!({
                "action": "search_tickets",
                "jql": "project = PROJ",
                "max_results": 2
            }))
            .await
            .unwrap();

        assert!(result.success, "unexpected error: {:?}", result.error);
        let output: Value = serde_json::from_str(&result.output).unwrap();
        assert_eq!(output.as_array().unwrap().len(), 2);
        server.verify().await;
    }

    #[tokio::test]
    async fn server_search_uses_bearer_auth_v2_endpoint_and_start_at() {
        use wiremock::matchers::{body_json, header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let fields = json!([
            "summary", "priority", "status", "assignee", "created", "updated"
        ]);

        let first_body = json!({
            "jql": "project = PROJ",
            "startAt": 0,
            "maxResults": 2,
            "fields": fields
        });
        Mock::given(method("POST"))
            .and(path("/rest/api/2/search"))
            .and(header("authorization", "Bearer pat-token-abc"))
            .and(body_json(&first_body))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "issues": [basic_search_issue("PROJ-1")],
                "total": 2
            })))
            .expect(1)
            .mount(&server)
            .await;

        let second_body = json!({
            "jql": "project = PROJ",
            "startAt": 1,
            "maxResults": 1,
            "fields": fields
        });
        Mock::given(method("POST"))
            .and(path("/rest/api/2/search"))
            .and(header("authorization", "Bearer pat-token-abc"))
            .and(body_json(&second_body))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "issues": [basic_search_issue("PROJ-2")],
                "total": 2
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool =
            test_tool_with_base_url(server.uri(), None, "pat-token-abc", vec!["search_tickets"]);
        let result = tool
            .execute(json!({
                "action": "search_tickets",
                "jql": "project = PROJ",
                "max_results": 2
            }))
            .await
            .unwrap();

        assert!(result.success, "unexpected error: {:?}", result.error);
        let output: Value = serde_json::from_str(&result.output).unwrap();
        assert_eq!(output.as_array().unwrap().len(), 2);
        server.verify().await;
    }

    #[tokio::test]
    async fn cloud_comment_posts_adf_body_to_v3_endpoint() {
        use wiremock::matchers::{body_json, header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let comment = "This is **important**.\n- Check the logs";
        let expected_body = json!({ "body": build_adf(comment, &HashMap::new()) });
        let auth = basic_auth_header("test@example.com", "test-token");

        Mock::given(method("POST"))
            .and(path("/rest/api/3/issue/PROJ-1/comment"))
            .and(header("authorization", auth.as_str()))
            .and(body_json(&expected_body))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "id": "10000",
                "author": { "displayName": "Jane" },
                "created": "2024-01-15T10:00:00.000Z"
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["comment_ticket"],
        );
        let result = tool
            .execute(json!({
                "action": "comment_ticket",
                "issue_key": "PROJ-1",
                "comment": comment
            }))
            .await
            .unwrap();

        assert!(result.success, "unexpected error: {:?}", result.error);
        server.verify().await;
    }

    #[tokio::test]
    async fn server_comment_posts_plain_text_body_to_v2_endpoint() {
        use wiremock::matchers::{body_json, header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let comment = "Hi @john@company.com, this is **important**.\n- Check the logs";
        let expected_body = json!({ "body": comment });

        Mock::given(method("POST"))
            .and(path("/rest/api/2/issue/PROJ-1/comment"))
            .and(header("authorization", "Bearer pat-token-abc"))
            .and(body_json(&expected_body))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "id": "10001",
                "author": { "displayName": "Jane" },
                "created": "2024-01-15T10:00:00.000Z"
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool =
            test_tool_with_base_url(server.uri(), None, "pat-token-abc", vec!["comment_ticket"]);
        let result = tool
            .execute(json!({
                "action": "comment_ticket",
                "issue_key": "PROJ-1",
                "comment": comment
            }))
            .await
            .unwrap();

        assert!(result.success, "unexpected error: {:?}", result.error);
        server.verify().await;
    }

    #[test]
    fn parameters_schema_has_required_action() {
        let schema = test_tool(vec!["get_ticket"]).parameters_schema();
        let required = schema["required"].as_array().unwrap();
        assert!(required.iter().any(|v| v.as_str() == Some("action")));
    }

    #[test]
    fn parameters_schema_defines_all_actions() {
        let schema = test_tool(vec!["get_ticket"]).parameters_schema();
        let actions = schema["properties"]["action"]["enum"].as_array().unwrap();
        let action_strs: Vec<&str> = actions.iter().filter_map(|v| v.as_str()).collect();
        assert!(action_strs.contains(&"get_ticket"));
        assert!(action_strs.contains(&"search_tickets"));
        assert!(action_strs.contains(&"comment_ticket"));
    }

    #[test]
    fn parameters_schema_describes_cloud_and_server_comment_modes() {
        let schema = test_tool(vec!["comment_ticket"]).parameters_schema();
        let description = schema["properties"]["comment"]["description"]
            .as_str()
            .unwrap();

        assert!(description.contains("Jira Cloud mode"));
        assert!(description.contains("Atlassian Document Format"));
        assert!(description.contains("Jira Server/Data Center mode"));
        assert!(description.contains("plain text"));
    }

    #[tokio::test]
    async fn execute_missing_action_returns_error() {
        let result = test_tool(vec!["get_ticket"])
            .execute(json!({}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("action"));
    }

    #[tokio::test]
    async fn execute_unknown_action_returns_error() {
        let result = test_tool(vec!["get_ticket"])
            .execute(json!({"action": "delete_ticket"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("Unknown action"));
    }

    #[tokio::test]
    async fn execute_disallowed_action_returns_error() {
        let result = test_tool(vec!["get_ticket"])
            .execute(json!({"action": "comment_ticket"}))
            .await
            .unwrap();
        assert!(!result.success);
        let err = result.error.unwrap();
        assert!(err.contains("not enabled"));
        assert!(err.contains("allowed_actions"));
    }

    #[tokio::test]
    async fn execute_get_ticket_missing_key_returns_error() {
        let result = test_tool(vec!["get_ticket"])
            .execute(json!({"action": "get_ticket"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("issue_key"));
    }

    #[tokio::test]
    async fn execute_search_tickets_missing_jql_returns_error() {
        let result = test_tool(vec!["get_ticket", "search_tickets"])
            .execute(json!({"action": "search_tickets"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("jql"));
    }

    #[tokio::test]
    async fn execute_comment_ticket_missing_key_returns_error() {
        let result = test_tool(vec!["get_ticket", "comment_ticket"])
            .execute(json!({"action": "comment_ticket", "comment": "hello"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("issue_key"));
    }

    #[tokio::test]
    async fn execute_comment_ticket_missing_comment_returns_error() {
        let result = test_tool(vec!["get_ticket", "comment_ticket"])
            .execute(json!({"action": "comment_ticket", "issue_key": "PROJ-1"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("comment"));
    }

    #[tokio::test]
    async fn execute_comment_ticket_empty_comment_returns_error() {
        let result = test_tool(vec!["get_ticket", "comment_ticket"])
            .execute(json!({"action": "comment_ticket", "issue_key": "PROJ-1", "comment": "   "}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("comment"));
    }

    #[tokio::test]
    async fn execute_comment_blocked_in_readonly_mode() {
        let security = Arc::new(SecurityPolicy {
            autonomy: AutonomyLevel::ReadOnly,
            ..SecurityPolicy::default()
        });
        let tool = JiraTool::new(
            "https://test.atlassian.net".into(),
            Some("test@example.com".into()),
            "token".into(),
            vec!["get_ticket".into(), "comment_ticket".into()],
            security,
            30,
        );
        let result = tool
            .execute(json!({
                "action": "comment_ticket",
                "issue_key": "PROJ-1",
                "comment": "hello"
            }))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("read-only"));
    }

    // ── myself action ────────────────────────────────────────────────────────

    #[test]
    fn parameters_schema_includes_myself_action() {
        let schema = test_tool(vec!["myself"]).parameters_schema();
        let actions = schema["properties"]["action"]["enum"].as_array().unwrap();
        let action_strs: Vec<&str> = actions.iter().filter_map(|v| v.as_str()).collect();
        assert!(action_strs.contains(&"myself"));
    }

    #[tokio::test]
    async fn execute_myself_disallowed_returns_error() {
        let result = test_tool(vec!["get_ticket"])
            .execute(json!({"action": "myself"}))
            .await
            .unwrap();
        assert!(!result.success);
        let err = result.error.unwrap();
        assert!(err.contains("not enabled"));
        assert!(err.contains("allowed_actions"));
    }

    #[tokio::test]
    async fn execute_myself_not_blocked_in_readonly_mode() {
        // myself is a Read operation — the security policy should not block it.
        // The call will fail at the HTTP level (no real server), not at the
        // policy level, so the error must NOT contain "read-only".
        let security = Arc::new(SecurityPolicy {
            autonomy: AutonomyLevel::ReadOnly,
            ..SecurityPolicy::default()
        });
        let tool = JiraTool::new(
            "https://test.atlassian.net".into(),
            Some("test@example.com".into()),
            "token".into(),
            vec!["myself".into()],
            security,
            30,
        );
        let result = tool.execute(json!({"action": "myself"})).await.unwrap();
        assert!(!result.success);
        assert!(!result.error.as_deref().unwrap_or("").contains("read-only"));
    }

    // ── Issue key validation ──────────────────────────────────────────────────

    #[test]
    fn validate_issue_key_accepts_valid_keys() {
        assert!(validate_issue_key("PROJ-1").is_ok());
        assert!(validate_issue_key("PROJ-123").is_ok());
        assert!(validate_issue_key("AB-99").is_ok());
        assert!(validate_issue_key("MYPROJECT-1000").is_ok());
        assert!(validate_issue_key("proj-1").is_ok());
        assert!(validate_issue_key("proj-123").is_ok());
    }

    #[test]
    fn validate_issue_key_rejects_path_traversal() {
        assert!(validate_issue_key("../../etc/passwd").is_err());
        assert!(validate_issue_key("../other").is_err());
    }

    #[test]
    fn validate_issue_key_rejects_malformed() {
        assert!(validate_issue_key("PROJ").is_err()); // no number
        assert!(validate_issue_key("PROJ-").is_err()); // empty number
        assert!(validate_issue_key("-123").is_err()); // no project
        assert!(validate_issue_key("PROJ-12x").is_err()); // non-digit in number
    }

    // ── ADF builder unit tests ────────────────────────────────────────────────

    #[test]
    fn build_adf_plain_text() {
        let adf = build_adf("Hello world", &HashMap::new());
        assert_eq!(adf["type"], "doc");
        assert_eq!(adf["version"], 1);
        let para = &adf["content"][0];
        assert_eq!(para["type"], "paragraph");
        assert_eq!(para["content"][0]["text"], "Hello world");
    }

    #[test]
    fn build_adf_bold() {
        let adf = build_adf("**bold**", &HashMap::new());
        let text_node = &adf["content"][0]["content"][0];
        assert_eq!(text_node["text"], "bold");
        assert_eq!(text_node["marks"][0]["type"], "strong");
    }

    #[test]
    fn build_adf_unmatched_bold_is_literal() {
        let adf = build_adf("**no closing", &HashMap::new());
        let text = &adf["content"][0]["content"][0]["text"];
        assert!(text.as_str().unwrap().contains("**no closing"));
    }

    #[test]
    fn build_adf_bullet_list() {
        let adf = build_adf("- first\n- second", &HashMap::new());
        let list = &adf["content"][0];
        assert_eq!(list["type"], "bulletList");
        assert_eq!(list["content"].as_array().unwrap().len(), 2);
        assert_eq!(list["content"][0]["type"], "listItem");
    }

    #[test]
    fn build_adf_mention_resolved() {
        let mut mentions = HashMap::new();
        mentions.insert(
            "john@company.com".to_string(),
            ("acc-123".to_string(), "John Doe".to_string()),
        );
        let adf = build_adf("Hi @john@company.com done", &mentions);
        let content = &adf["content"][0]["content"];
        let mention = content
            .as_array()
            .unwrap()
            .iter()
            .find(|n| n["type"] == "mention")
            .unwrap();
        assert_eq!(mention["attrs"]["id"], "acc-123");
        assert_eq!(mention["attrs"]["text"], "@John Doe");
    }

    #[test]
    fn build_adf_unresolved_mention_rendered_as_plain_text() {
        let adf = build_adf("Hi @unknown@example.com", &HashMap::new());
        let text = &adf["content"][0]["content"][0]["text"];
        assert!(text.as_str().unwrap().contains("@unknown@example.com"));
    }

    #[test]
    fn extract_emails_finds_at_prefixed_emails() {
        let emails = extract_emails("Hello @john@company.com and @jane@corp.io done");
        assert_eq!(emails, vec!["john@company.com", "jane@corp.io"]);
    }

    #[test]
    fn extract_emails_deduplicates() {
        let emails = extract_emails("@a@b.com @a@b.com");
        assert_eq!(emails.len(), 1);
    }

    #[test]
    fn extract_emails_deduplicates_non_adjacent() {
        let emails = extract_emails("@a@b.com @c@d.com @a@b.com");
        assert_eq!(emails, vec!["a@b.com", "c@d.com"]);
    }

    #[test]
    fn extract_emails_strips_trailing_punctuation() {
        let emails = extract_emails("@john@company.com,");
        assert_eq!(emails, vec!["john@company.com"]);
    }

    #[test]
    fn extract_emails_strips_leading_punctuation() {
        let emails = extract_emails("@(john@company.com)");
        assert_eq!(emails, vec!["john@company.com"]);
    }

    #[test]
    fn shape_basic_search_extracts_expected_fields() {
        let raw = json!({
            "key": "PROJ-1",
            "fields": {
                "summary": "Fix bug",
                "status": { "name": "In Progress" },
                "priority": { "name": "High" },
                "assignee": { "displayName": "Jane" },
                "created": "2024-01-15T10:00:00.000Z",
                "updated": "2024-03-01T12:00:00.000Z"
            }
        });
        let shaped = shape_basic_search(&raw);
        assert_eq!(shaped["key"], "PROJ-1");
        assert_eq!(shaped["summary"], "Fix bug");
        assert_eq!(shaped["status"], "In Progress");
        assert_eq!(shaped["priority"], "High");
        assert_eq!(shaped["assignee"], "Jane");
        assert_eq!(shaped["created"], "2024-01-15");
        assert_eq!(shaped["updated"], "2024-03-01");
    }

    #[test]
    fn shape_changelog_extracts_key_and_changelog() {
        let raw = json!({
            "key": "PROJ-42",
            "changelog": { "histories": [] },
            "fields": {}
        });
        let shaped = shape_changelog(&raw);
        assert_eq!(shaped["key"], "PROJ-42");
        assert!(shaped.get("changelog").is_some());
        assert!(shaped.get("fields").is_none());
    }

    #[test]
    fn shape_comment_response_extracts_id_author_created() {
        let raw = json!({
            "id": "12345",
            "author": { "displayName": "Alice", "accountId": "abc" },
            "created": "2024-06-01T09:00:00.000Z",
            "body": { "type": "doc" },
            "self": "https://internal.url"
        });
        let shaped = shape_comment_response(&raw);
        assert_eq!(shaped["id"], "12345");
        assert_eq!(shaped["author"], "Alice");
        assert_eq!(shaped["created"], "2024-06-01");
        assert!(shaped.get("body").is_none());
        assert!(shaped.get("self").is_none());
    }

    // ── date_prefix helper ─────────────────────────────────────────────────

    #[test]
    fn date_prefix_normal_date_string() {
        assert_eq!(date_prefix("2024-01-15T10:00:00.000Z"), "2024-01-15");
    }

    #[test]
    fn date_prefix_empty_string() {
        assert_eq!(date_prefix(""), "");
    }

    #[test]
    fn date_prefix_short_string() {
        assert_eq!(date_prefix("2024"), "2024");
    }

    #[test]
    fn date_prefix_exactly_ten_chars() {
        assert_eq!(date_prefix("2024-01-15"), "2024-01-15");
    }

    #[test]
    fn shape_basic_uses_o1_comment_lookup() {
        // Verify that comments are matched by ID, not by position.
        let raw = json!({
            "key": "PROJ-1",
            "fields": {
                "summary": "s", "priority": {"name":"P"}, "status": {"name":"S"},
                "assignee": {"displayName":"A"},
                "created": "2024-01-01T00:00:00.000Z",
                "updated": "2024-01-01T00:00:00.000Z",
                "comment": {
                    "comments": [
                        { "id": "2", "author": {"displayName":"Bob"}, "created": "2024-01-02T00:00:00.000Z" },
                        { "id": "1", "author": {"displayName":"Alice"}, "created": "2024-01-01T00:00:00.000Z" }
                    ]
                }
            },
            "renderedFields": {
                "description": "",
                "comment": {
                    "comments": [
                        { "id": "1", "body": "Alice's body" },
                        { "id": "2", "body": "Bob's body" }
                    ]
                }
            }
        });
        let shaped = shape_basic(&raw);
        // Comment with id "2" (Bob) should get Bob's rendered body, not Alice's
        assert_eq!(shaped["comments"][0]["author"], "Bob");
        assert_eq!(shaped["comments"][0]["body"], "Bob's body");
        assert_eq!(shaped["comments"][1]["author"], "Alice");
        assert_eq!(shaped["comments"][1]["body"], "Alice's body");
    }

    // ── list_projects action ────────────────────────────────────────────────

    #[test]
    fn parameters_schema_includes_list_projects_action() {
        let schema = test_tool(vec!["list_projects"]).parameters_schema();
        let actions = schema["properties"]["action"]["enum"].as_array().unwrap();
        let action_strs: Vec<&str> = actions.iter().filter_map(|v| v.as_str()).collect();
        assert!(action_strs.contains(&"list_projects"));
    }

    #[tokio::test]
    async fn execute_list_projects_disallowed_returns_error() {
        let result = test_tool(vec!["get_ticket"])
            .execute(json!({"action": "list_projects"}))
            .await
            .unwrap();
        assert!(!result.success);
        let err = result.error.unwrap();
        assert!(err.contains("not enabled"));
        assert!(err.contains("allowed_actions"));
    }

    #[tokio::test]
    async fn execute_list_projects_not_blocked_in_readonly_mode() {
        let security = Arc::new(SecurityPolicy {
            autonomy: AutonomyLevel::ReadOnly,
            ..SecurityPolicy::default()
        });
        let tool = JiraTool::new(
            "https://127.0.0.1:1".into(),
            Some("test@example.com".into()),
            "token".into(),
            vec!["list_projects".into()],
            security,
            30,
        );
        let result = tool
            .execute(json!({"action": "list_projects"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(
            !result.error.as_deref().unwrap_or("").contains("read-only"),
            "error should not mention read-only policy: {:?}",
            result.error
        );
    }

    #[test]
    fn shape_projects_extracts_expected_fields() {
        let projects = json!([
            { "key": "AT", "name": "ALL TASKS", "projectTypeKey": "business", "style": "next-gen" },
            { "key": "GP", "name": "G-PROJECT", "projectTypeKey": "software", "style": "next-gen" }
        ]);
        let statuses: Vec<Value> = vec![
            json!([
                { "name": "Task", "statuses": [
                    { "name": "To Do" }, { "name": "In Progress" }, { "name": "Collecting Intel" }, { "name": "Done" }
                ]},
                { "name": "Sub-task", "statuses": [
                    { "name": "To Do" }, { "name": "Verification" }
                ]}
            ]),
            json!([
                { "name": "Task", "statuses": [
                    { "name": "To Do" }, { "name": "Design" }, { "name": "Done" }
                ]},
                { "name": "Epic", "statuses": [
                    { "name": "To Do" }, { "name": "Done" }
                ]}
            ]),
        ];
        let shaped = shape_projects(projects.as_array().unwrap(), &statuses);
        let arr = &shaped;

        assert_eq!(arr.len(), 2);

        assert_eq!(arr[0]["key"], "AT");
        assert_eq!(arr[0]["name"], "ALL TASKS");
        assert_eq!(arr[0]["projectType"], "business");
        let at_statuses: Vec<&str> = arr[0]["statuses"]
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|v| v.as_str())
            .collect();
        assert_eq!(
            at_statuses,
            vec![
                "Collecting Intel",
                "Done",
                "In Progress",
                "To Do",
                "Verification",
            ]
        );
        let at_types: Vec<&str> = arr[0]["issueTypes"]
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|v| v.as_str())
            .collect();
        assert!(at_types.contains(&"Task"));
        assert!(at_types.contains(&"Sub-task"));

        assert_eq!(arr[1]["key"], "GP");
        assert_eq!(arr[1]["projectType"], "software");
        let gp_statuses: Vec<&str> = arr[1]["statuses"]
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|v| v.as_str())
            .collect();
        assert_eq!(gp_statuses, vec!["Design", "Done", "To Do"]);

        assert!(
            arr[0].get("users").is_none(),
            "users should not be in per-project data"
        );
    }

    #[test]
    fn shape_projects_sorts_statuses_alphabetically() {
        let projects = json!([
            { "key": "P", "name": "P", "projectTypeKey": "software", "style": "next-gen" }
        ]);
        let statuses: Vec<Value> = vec![json!([
            { "name": "Task", "statuses": [
                { "name": "Done" }, { "name": "Custom" }, { "name": "To Do" }, { "name": "Alpha" }
            ]}
        ])];
        let shaped = shape_projects(projects.as_array().unwrap(), &statuses);
        let ordered: Vec<&str> = shaped[0]["statuses"]
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|v| v.as_str())
            .collect();
        assert_eq!(ordered, vec!["Alpha", "Custom", "Done", "To Do"]);
    }

    #[test]
    fn shape_projects_empty_inputs() {
        let shaped = shape_projects(&[], &[]);
        assert_eq!(shaped.len(), 0);
    }

    // ── list_transitions / transition_ticket / create_ticket ─────────────────

    #[test]
    fn parameters_schema_includes_new_actions() {
        let schema = test_tool(vec!["get_ticket"]).parameters_schema();
        let actions = schema["properties"]["action"]["enum"].as_array().unwrap();
        let action_strs: Vec<&str> = actions.iter().filter_map(|v| v.as_str()).collect();
        assert!(action_strs.contains(&"list_transitions"));
        assert!(action_strs.contains(&"transition_ticket"));
        assert!(action_strs.contains(&"create_ticket"));
    }

    #[test]
    fn parameters_schema_describes_transition_params() {
        let schema = test_tool(vec!["transition_ticket"]).parameters_schema();
        let props = &schema["properties"];
        assert!(props["transition_id"].is_object());
        assert!(props["transition_name"].is_object());
    }

    #[test]
    fn parameters_schema_describes_create_params() {
        let schema = test_tool(vec!["create_ticket"]).parameters_schema();
        let props = &schema["properties"];
        for key in [
            "project_key",
            "issue_type",
            "summary",
            "description",
            "assignee",
            "labels",
            "parent_key",
        ] {
            assert!(props[key].is_object(), "missing schema property: {key}");
        }
    }

    #[tokio::test]
    async fn execute_list_transitions_disallowed_returns_error() {
        let result = test_tool(vec!["get_ticket"])
            .execute(json!({"action": "list_transitions", "issue_key": "PROJ-1"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("not enabled"));
    }

    #[tokio::test]
    async fn execute_transition_ticket_blocked_in_readonly_mode() {
        let security = Arc::new(SecurityPolicy {
            autonomy: AutonomyLevel::ReadOnly,
            ..SecurityPolicy::default()
        });
        let tool = JiraTool::new(
            "https://test.atlassian.net".into(),
            Some("test@example.com".into()),
            "token".into(),
            vec!["transition_ticket".into()],
            security,
            30,
        );
        let result = tool
            .execute(json!({
                "action": "transition_ticket",
                "issue_key": "PROJ-1",
                "transition_id": "31"
            }))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("read-only"));
    }

    #[tokio::test]
    async fn execute_create_ticket_blocked_in_readonly_mode() {
        let security = Arc::new(SecurityPolicy {
            autonomy: AutonomyLevel::ReadOnly,
            ..SecurityPolicy::default()
        });
        let tool = JiraTool::new(
            "https://test.atlassian.net".into(),
            Some("test@example.com".into()),
            "token".into(),
            vec!["create_ticket".into()],
            security,
            30,
        );
        let result = tool
            .execute(json!({
                "action": "create_ticket",
                "project_key": "PROJ",
                "issue_type": "Task",
                "summary": "test"
            }))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("read-only"));
    }

    #[tokio::test]
    async fn execute_list_transitions_not_blocked_in_readonly_mode() {
        let security = Arc::new(SecurityPolicy {
            autonomy: AutonomyLevel::ReadOnly,
            ..SecurityPolicy::default()
        });
        let tool = JiraTool::new(
            "https://127.0.0.1:1".into(),
            Some("test@example.com".into()),
            "token".into(),
            vec!["list_transitions".into()],
            security,
            30,
        );
        let result = tool
            .execute(json!({"action": "list_transitions", "issue_key": "PROJ-1"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(
            !result.error.as_deref().unwrap_or("").contains("read-only"),
            "list_transitions should be a Read op, but error mentioned read-only: {:?}",
            result.error
        );
    }

    #[tokio::test]
    async fn execute_list_transitions_missing_key_returns_error() {
        let result = test_tool(vec!["list_transitions"])
            .execute(json!({"action": "list_transitions"}))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("issue_key"));
    }

    #[tokio::test]
    async fn execute_transition_ticket_missing_id_and_name_returns_error() {
        let result = test_tool(vec!["transition_ticket"])
            .execute(json!({"action": "transition_ticket", "issue_key": "PROJ-1"}))
            .await
            .unwrap();
        assert!(!result.success);
        let err = result.error.unwrap();
        assert!(err.contains("transition_id") && err.contains("transition_name"));
    }

    #[tokio::test]
    async fn execute_transition_ticket_both_id_and_name_returns_error() {
        let result = test_tool(vec!["transition_ticket"])
            .execute(json!({
                "action": "transition_ticket",
                "issue_key": "PROJ-1",
                "transition_id": "31",
                "transition_name": "In Progress"
            }))
            .await
            .unwrap();
        assert!(!result.success);
        assert!(result.error.as_deref().unwrap().contains("only one"));
    }

    #[tokio::test]
    async fn execute_create_ticket_missing_required_fields_returns_error() {
        let tool = test_tool(vec!["create_ticket"]);
        // Missing project_key
        let r1 = tool
            .execute(json!({
                "action": "create_ticket",
                "issue_type": "Task",
                "summary": "x"
            }))
            .await
            .unwrap();
        assert!(!r1.success);
        assert!(r1.error.as_deref().unwrap().contains("project_key"));
        // Missing issue_type
        let r2 = tool
            .execute(json!({
                "action": "create_ticket",
                "project_key": "PROJ",
                "summary": "x"
            }))
            .await
            .unwrap();
        assert!(!r2.success);
        assert!(r2.error.as_deref().unwrap().contains("issue_type"));
        // Missing summary
        let r3 = tool
            .execute(json!({
                "action": "create_ticket",
                "project_key": "PROJ",
                "issue_type": "Task"
            }))
            .await
            .unwrap();
        assert!(!r3.success);
        assert!(r3.error.as_deref().unwrap().contains("summary"));
    }

    #[tokio::test]
    async fn cloud_list_transitions_returns_shaped_response() {
        use wiremock::matchers::{header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let auth = basic_auth_header("test@example.com", "test-token");

        Mock::given(method("GET"))
            .and(path("/rest/api/3/issue/PROJ-1/transitions"))
            .and(header("authorization", auth.as_str()))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "transitions": [
                    { "id": "11", "name": "To Do",       "to": { "name": "To Do" }, "isAvailable": true },
                    { "id": "21", "name": "In Progress", "to": { "name": "In Progress" } },
                    { "id": "31", "name": "Done",        "to": { "name": "Done" } }
                ]
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["list_transitions"],
        );
        let result = tool
            .execute(json!({"action": "list_transitions", "issue_key": "PROJ-1"}))
            .await
            .unwrap();
        assert!(result.success, "unexpected error: {:?}", result.error);
        let output: Value = serde_json::from_str(&result.output).unwrap();
        let arr = output["transitions"].as_array().unwrap();
        assert_eq!(arr.len(), 3);
        assert_eq!(arr[1]["id"], "21");
        assert_eq!(arr[1]["name"], "In Progress");
        assert_eq!(arr[1]["to_status"], "In Progress");
        // Verbose Jira fields are dropped.
        assert!(arr[0].get("isAvailable").is_none());
        server.verify().await;
    }

    #[tokio::test]
    async fn cloud_transition_ticket_by_id_posts_expected_body() {
        use wiremock::matchers::{body_json, header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let auth = basic_auth_header("test@example.com", "test-token");
        let body = json!({ "transition": { "id": "31" } });

        Mock::given(method("POST"))
            .and(path("/rest/api/3/issue/PROJ-1/transitions"))
            .and(header("authorization", auth.as_str()))
            .and(body_json(&body))
            .respond_with(ResponseTemplate::new(204))
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["transition_ticket"],
        );
        let result = tool
            .execute(json!({
                "action": "transition_ticket",
                "issue_key": "PROJ-1",
                "transition_id": "31"
            }))
            .await
            .unwrap();
        assert!(result.success, "unexpected error: {:?}", result.error);
        let output: Value = serde_json::from_str(&result.output).unwrap();
        assert_eq!(output["ok"], true);
        assert_eq!(output["transition_id"], "31");
        assert_eq!(output["issue_key"], "PROJ-1");
        server.verify().await;
    }

    #[tokio::test]
    async fn server_transition_ticket_by_name_resolves_then_posts_to_v2() {
        use wiremock::matchers::{body_json, header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;

        Mock::given(method("GET"))
            .and(path("/rest/api/2/issue/PROJ-7/transitions"))
            .and(header("authorization", "Bearer pat-token-abc"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "transitions": [
                    { "id": "21", "name": "In Progress", "to": { "name": "In Progress" } },
                    { "id": "31", "name": "Done", "to": { "name": "Done" } }
                ]
            })))
            .expect(1)
            .mount(&server)
            .await;

        let post_body = json!({ "transition": { "id": "21" } });
        Mock::given(method("POST"))
            .and(path("/rest/api/2/issue/PROJ-7/transitions"))
            .and(header("authorization", "Bearer pat-token-abc"))
            .and(body_json(&post_body))
            .respond_with(ResponseTemplate::new(204))
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            None,
            "pat-token-abc",
            vec!["transition_ticket"],
        );
        let result = tool
            .execute(json!({
                "action": "transition_ticket",
                "issue_key": "PROJ-7",
                "transition_name": "in progress"
            }))
            .await
            .unwrap();
        assert!(result.success, "unexpected error: {:?}", result.error);
        let output: Value = serde_json::from_str(&result.output).unwrap();
        assert_eq!(output["transition_id"], "21");
        server.verify().await;
    }

    #[tokio::test]
    async fn transition_ticket_unknown_name_returns_error_with_available() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;

        Mock::given(method("GET"))
            .and(path("/rest/api/3/issue/PROJ-1/transitions"))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "transitions": [
                    { "id": "21", "name": "In Progress", "to": { "name": "In Progress" } },
                    { "id": "31", "name": "Done", "to": { "name": "Done" } }
                ]
            })))
            .expect(1)
            .mount(&server)
            .await;

        // No POST mock — if the tool tried to POST, the test would fail with
        // an unmocked request error from wiremock's verify().
        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["transition_ticket"],
        );
        let result = tool
            .execute(json!({
                "action": "transition_ticket",
                "issue_key": "PROJ-1",
                "transition_name": "Reticulate Splines"
            }))
            .await
            .unwrap();
        assert!(!result.success);
        let err = result.error.unwrap();
        assert!(err.contains("Reticulate Splines"));
        assert!(err.contains("In Progress"));
        assert!(err.contains("Done"));
        server.verify().await;
    }

    #[tokio::test]
    async fn cloud_create_ticket_minimal_posts_expected_body() {
        use wiremock::matchers::{body_json, header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        let auth = basic_auth_header("test@example.com", "test-token");
        let expected = json!({
            "fields": {
                "project":   { "key": "PROJ" },
                "issuetype": { "name": "Task" },
                "summary":   "My new task"
            }
        });

        Mock::given(method("POST"))
            .and(path("/rest/api/3/issue"))
            .and(header("authorization", auth.as_str()))
            .and(body_json(&expected))
            .respond_with(ResponseTemplate::new(201).set_body_json(json!({
                "id":   "10042",
                "key":  "PROJ-99",
                "self": "https://test.atlassian.net/rest/api/3/issue/10042"
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["create_ticket"],
        );
        let result = tool
            .execute(json!({
                "action": "create_ticket",
                "project_key": "PROJ",
                "issue_type": "Task",
                "summary": "My new task"
            }))
            .await
            .unwrap();
        assert!(result.success, "unexpected error: {:?}", result.error);
        let output: Value = serde_json::from_str(&result.output).unwrap();
        assert_eq!(output["key"], "PROJ-99");
        assert_eq!(output["id"], "10042");
        assert_eq!(
            output["browse_url"].as_str().unwrap(),
            format!("{}/browse/PROJ-99", server.uri())
        );
        server.verify().await;
    }

    #[tokio::test]
    async fn cloud_create_ticket_with_description_uses_adf() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, Request, ResponseTemplate};

        let server = MockServer::start().await;

        Mock::given(method("POST"))
            .and(path("/rest/api/3/issue"))
            .respond_with(ResponseTemplate::new(201).set_body_json(json!({
                "id": "1", "key": "PROJ-1", "self": "x"
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["create_ticket"],
        );
        tool.execute(json!({
            "action": "create_ticket",
            "project_key": "PROJ",
            "issue_type": "Task",
            "summary": "s",
            "description": "**bold** body"
        }))
        .await
        .unwrap();

        let received = &server.received_requests().await.unwrap();
        let req: &Request = received.last().unwrap();
        let body: Value = serde_json::from_slice(&req.body).unwrap();
        let desc = &body["fields"]["description"];
        assert_eq!(desc["type"], "doc", "description must be ADF in Cloud mode");
        assert_eq!(desc["version"], 1);
    }

    #[tokio::test]
    async fn server_create_ticket_with_description_uses_plain_string() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, Request, ResponseTemplate};

        let server = MockServer::start().await;

        Mock::given(method("POST"))
            .and(path("/rest/api/2/issue"))
            .respond_with(ResponseTemplate::new(201).set_body_json(json!({
                "id": "1", "key": "PROJ-1", "self": "x"
            })))
            .expect(1)
            .mount(&server)
            .await;

        let tool =
            test_tool_with_base_url(server.uri(), None, "pat-token-abc", vec!["create_ticket"]);
        tool.execute(json!({
            "action": "create_ticket",
            "project_key": "PROJ",
            "issue_type": "Task",
            "summary": "s",
            "description": "plain text"
        }))
        .await
        .unwrap();

        let received = &server.received_requests().await.unwrap();
        let req: &Request = received.last().unwrap();
        let body: Value = serde_json::from_slice(&req.body).unwrap();
        assert_eq!(
            body["fields"]["description"], "plain text",
            "description must be a plain string in Server mode"
        );
    }

    #[tokio::test]
    async fn cloud_create_ticket_with_assignee_uses_account_id() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, Request, ResponseTemplate};

        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/rest/api/3/issue"))
            .respond_with(ResponseTemplate::new(201).set_body_json(json!({
                "id": "1", "key": "PROJ-1", "self": "x"
            })))
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["create_ticket"],
        );
        tool.execute(json!({
            "action": "create_ticket",
            "project_key": "PROJ",
            "issue_type": "Task",
            "summary": "s",
            "assignee": "acc-123"
        }))
        .await
        .unwrap();

        let req: Request = server
            .received_requests()
            .await
            .unwrap()
            .last()
            .cloned()
            .unwrap();
        let body: Value = serde_json::from_slice(&req.body).unwrap();
        assert_eq!(body["fields"]["assignee"]["accountId"], "acc-123");
        assert!(body["fields"]["assignee"].get("name").is_none());
    }

    #[tokio::test]
    async fn server_create_ticket_with_assignee_uses_username() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, Request, ResponseTemplate};

        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/rest/api/2/issue"))
            .respond_with(ResponseTemplate::new(201).set_body_json(json!({
                "id": "1", "key": "PROJ-1", "self": "x"
            })))
            .mount(&server)
            .await;

        let tool =
            test_tool_with_base_url(server.uri(), None, "pat-token-abc", vec!["create_ticket"]);
        tool.execute(json!({
            "action": "create_ticket",
            "project_key": "PROJ",
            "issue_type": "Task",
            "summary": "s",
            "assignee": "jdoe"
        }))
        .await
        .unwrap();

        let req: Request = server
            .received_requests()
            .await
            .unwrap()
            .last()
            .cloned()
            .unwrap();
        let body: Value = serde_json::from_slice(&req.body).unwrap();
        assert_eq!(body["fields"]["assignee"]["name"], "jdoe");
        assert!(body["fields"]["assignee"].get("accountId").is_none());
    }

    #[tokio::test]
    async fn cloud_create_ticket_jira_error_surfaces_body() {
        use wiremock::matchers::{method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let server = MockServer::start().await;
        Mock::given(method("POST"))
            .and(path("/rest/api/3/issue"))
            .respond_with(
                ResponseTemplate::new(400)
                    .set_body_string(r#"{"errors":{"customfield_12345":"Field is required"}}"#),
            )
            .expect(1)
            .mount(&server)
            .await;

        let tool = test_tool_with_base_url(
            server.uri(),
            Some("test@example.com".into()),
            "test-token",
            vec!["create_ticket"],
        );
        let result = tool
            .execute(json!({
                "action": "create_ticket",
                "project_key": "PROJ",
                "issue_type": "Task",
                "summary": "s"
            }))
            .await
            .unwrap();
        assert!(!result.success);
        let err = result.error.unwrap();
        assert!(err.contains("400"));
        assert!(err.contains("customfield_12345"));
        server.verify().await;
    }

    #[test]
    fn validate_project_key_accepts_valid_keys() {
        assert!(validate_project_key("PROJ").is_ok());
        assert!(validate_project_key("ABC123").is_ok());
        assert!(validate_project_key("p1").is_ok());
    }

    #[test]
    fn validate_project_key_rejects_invalid_keys() {
        assert!(validate_project_key("").is_err());
        assert!(validate_project_key("PROJ-1").is_err());
        assert!(validate_project_key("../etc").is_err());
        assert!(validate_project_key("PROJ ABC").is_err());
    }

    #[test]
    fn shape_transitions_extracts_minimal_fields() {
        let raw = json!({
            "transitions": [
                {
                    "id": "11", "name": "To Do",
                    "to": { "name": "To Do", "id": "10000", "self": "https://x" },
                    "isAvailable": true
                },
                {
                    "id": "21", "name": "In Progress",
                    "to": { "name": "In Progress" }
                }
            ]
        });
        let shaped = shape_transitions(&raw);
        assert_eq!(shaped.len(), 2);
        assert_eq!(shaped[0]["id"], "11");
        assert_eq!(shaped[0]["name"], "To Do");
        assert_eq!(shaped[0]["to_status"], "To Do");
        assert!(shaped[0].get("isAvailable").is_none());
    }

    #[test]
    fn shape_transitions_handles_missing_array() {
        assert!(shape_transitions(&json!({})).is_empty());
    }
}