huskies/server/src/service/timer/scheduled.rs

//! Generic scheduled timers: fire MCP calls or prompts at a configured instant,
//! with optional recurring re-arm.
//!
//! Separate from [`crate::service::timer::TimerStore`] which handles story-scoped
//! rate-limit retry timers.  This module provides a general-purpose scheduling
//! primitive with explicit action types and unique IDs.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};
use std::sync::Mutex;
use uuid::Uuid;

// ── Action ────────────────────────────────────────────────────────────────────

/// What to execute when a scheduled timer fires.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum TimerAction {
    /// Call an MCP tool by name with JSON arguments.
    Mcp {
        /// MCP tool name (e.g. `"start_agent"`, `"create_bug"`).
        method: String,
        /// JSON arguments object for the tool call.
        #[serde(default)]
        args: serde_json::Value,
    },
    /// Broadcast a reminder text to the server log.
    Prompt {
        /// Free-form reminder text logged when the timer fires.
        text: String,
    },
}

// ── Mode ─────────────────────────────────────────────────────────────────────

/// Whether the timer fires once or repeatedly.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "mode", rename_all = "snake_case")]
pub enum TimerMode {
    /// Fire once, then discard.
    Once,
    /// Fire, then re-arm at `fire_at + interval_secs`.
    Recurring {
        /// Seconds between firings.
        interval_secs: u64,
    },
}

// ── Entry ─────────────────────────────────────────────────────────────────────

/// A single generic scheduled timer entry.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ScheduledTimer {
    /// Unique stable identifier (UUID v4 short form, e.g. `"tm-a3f7b9c2"`).
    pub id: String,
    /// Optional human-readable label.
    pub label: Option<String>,
    /// UTC instant when this timer should next fire.
    pub fire_at: DateTime<Utc>,
    /// What to execute on fire.
    pub action: TimerAction,
    /// One-shot or recurring.
    pub mode: TimerMode,
    /// UTC instant when this timer was created.
    pub created_at: DateTime<Utc>,
}

impl ScheduledTimer {
    /// Generate a fresh timer ID.
    pub fn new_id() -> String {
        let id = Uuid::new_v4();
        let hex = id.as_simple().to_string();
        let prefix: String = hex.chars().take(8).collect();
        format!("tm-{prefix}")
    }
}

// ── Store ─────────────────────────────────────────────────────────────────────

/// Persistent store for generic scheduled timers, backed by a JSON file.
pub struct ScheduledTimerStore {
    path: PathBuf,
    timers: Mutex<Vec<ScheduledTimer>>,
}

impl ScheduledTimerStore {
    /// Load (or create empty) store from `path`.
    pub fn load(path: PathBuf) -> Self {
        let timers = if path.exists() {
            std::fs::read_to_string(&path)
                .ok()
                .and_then(|s| serde_json::from_str::<Vec<ScheduledTimer>>(&s).ok())
                .unwrap_or_default()
        } else {
            Vec::new()
        };
        Self {
            path,
            timers: Mutex::new(timers),
        }
    }

    fn save(path: &Path, timers: &[ScheduledTimer]) -> Result<(), String> {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).map_err(|e| format!("mkdir failed: {e}"))?;
        }
        let content =
            serde_json::to_string_pretty(timers).map_err(|e| format!("serialize failed: {e}"))?;
        std::fs::write(path, content).map_err(|e| format!("write failed: {e}"))
    }

    /// Add a timer.  Errors if a timer with the same ID already exists.
    pub fn add(&self, timer: ScheduledTimer) -> Result<(), String> {
        let mut timers = self.timers.lock().unwrap();
        if timers.iter().any(|t| t.id == timer.id) {
            return Err(format!("Timer with id '{}' already exists", timer.id));
        }
        timers.push(timer);
        Self::save(&self.path, &timers)
    }

    /// Remove a timer by ID.  Returns `true` if one was removed.
    pub fn remove_by_id(&self, id: &str) -> bool {
        let mut timers = self.timers.lock().unwrap();
        let before = timers.len();
        timers.retain(|t| t.id != id);
        let removed = timers.len() < before;
        if removed {
            let _ = Self::save(&self.path, &timers);
        }
        removed
    }

    /// Return all pending timers (cloned).
    pub fn list(&self) -> Vec<ScheduledTimer> {
        self.timers.lock().unwrap().clone()
    }

    /// Remove and return all timers whose `fire_at` ≤ `now`.
    pub fn take_due(&self, now: DateTime<Utc>) -> Vec<ScheduledTimer> {
        let mut timers = self.timers.lock().unwrap();
        let mut due = Vec::new();
        let mut remaining = Vec::new();
        for t in timers.drain(..) {
            if t.fire_at <= now {
                due.push(t);
            } else {
                remaining.push(t);
            }
        }
        *timers = remaining;
        if !due.is_empty() {
            let _ = Self::save(&self.path, &timers);
        }
        due
    }
}

// ── When parsing ──────────────────────────────────────────────────────────────

/// Parse a `when` string into `(fire_at, optional_interval_secs)`.
///
/// Accepted forms:
/// - Relative: `"in 2 hours"`, `"in 15 minutes"`, `"in 30 seconds"`,
///   `"2h"`, `"15m"`, `"30s"` (the `"in "` prefix is optional)
/// - Absolute: ISO 8601 / RFC 3339 timestamp (`"2026-05-15T10:00:00Z"`)
///
/// Returns the interval in seconds for relative durations so callers can
/// set up recurring re-arm intervals.
pub fn parse_when_str(
    when: &str,
    now: DateTime<Utc>,
) -> Result<(DateTime<Utc>, Option<u64>), String> {
    let trimmed = when.trim();

    // Strip optional "in " prefix, then attempt interval parse.
    let candidate = trimmed
        .strip_prefix("in ")
        .or_else(|| trimmed.strip_prefix("In "))
        .unwrap_or(trimmed);

    if let Some(secs) = parse_interval_str(candidate) {
        let fire_at = now + chrono::Duration::seconds(secs as i64);
        return Ok((fire_at, Some(secs)));
    }

    // Try ISO 8601 / RFC 3339 absolute timestamp.
    if let Ok(dt) = trimmed.parse::<DateTime<Utc>>() {
        return Ok((dt, None));
    }
    if let Ok(dt) = chrono::DateTime::parse_from_rfc3339(trimmed) {
        return Ok((dt.with_timezone(&Utc), None));
    }

    Err(format!(
        "Cannot parse 'when': '{when}'. \
         Use 'in 2 hours', '15 minutes', '2h', or an ISO 8601 timestamp."
    ))
}

/// Parse an interval string like `"2h"`, `"15m"`, `"30s"`, `"2 hours"`,
/// `"15 minutes"`, `"30 seconds"` into a number of seconds.
pub fn parse_interval_str(s: &str) -> Option<u64> {
    let s = s.trim().to_lowercase();
    let (num_str, unit_str) = split_num_unit(&s);
    let n: u64 = num_str.parse().ok()?;
    if n == 0 {
        return None;
    }
    match unit_str.trim() {
        "h" | "hr" | "hrs" | "hour" | "hours" => Some(n * 3600),
        "m" | "min" | "mins" | "minute" | "minutes" => Some(n * 60),
        "s" | "sec" | "secs" | "second" | "seconds" => Some(n),
        _ => None,
    }
}

/// Split a string like `"2hours"` or `"15 minutes"` into `("2", "hours")`.
fn split_num_unit(s: &str) -> (&str, &str) {
    let idx = s.find(|c: char| !c.is_ascii_digit()).unwrap_or(s.len());
    let (num, unit) = s.split_at(idx);
    (num, unit.trim_start_matches(' '))
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use chrono::TimeZone;
    use tempfile::TempDir;

    fn fixed_now() -> DateTime<Utc> {
        Utc.with_ymd_and_hms(2026, 5, 15, 10, 0, 0).unwrap()
    }

    // ── parse_interval_str ────────────────────────────────────────────────────

    #[test]
    fn parse_interval_hours_long() {
        assert_eq!(parse_interval_str("2 hours"), Some(7200));
    }

    #[test]
    fn parse_interval_hours_short() {
        assert_eq!(parse_interval_str("2h"), Some(7200));
    }

    #[test]
    fn parse_interval_minutes_long() {
        assert_eq!(parse_interval_str("15 minutes"), Some(900));
    }

    #[test]
    fn parse_interval_minutes_short() {
        assert_eq!(parse_interval_str("15m"), Some(900));
    }

    #[test]
    fn parse_interval_seconds_long() {
        assert_eq!(parse_interval_str("30 seconds"), Some(30));
    }

    #[test]
    fn parse_interval_seconds_short() {
        assert_eq!(parse_interval_str("30s"), Some(30));
    }

    #[test]
    fn parse_interval_zero_returns_none() {
        assert_eq!(parse_interval_str("0 hours"), None);
    }

    #[test]
    fn parse_interval_unknown_unit_returns_none() {
        assert_eq!(parse_interval_str("5 fortnights"), None);
    }

    // ── parse_when_str ────────────────────────────────────────────────────────

    #[test]
    fn parse_when_relative_with_in_prefix() {
        let now = fixed_now();
        let (fire_at, interval) = parse_when_str("in 2 hours", now).unwrap();
        assert_eq!(interval, Some(7200));
        assert_eq!(fire_at, now + chrono::Duration::seconds(7200));
    }

    #[test]
    fn parse_when_relative_without_in_prefix() {
        let now = fixed_now();
        let (fire_at, interval) = parse_when_str("15 minutes", now).unwrap();
        assert_eq!(interval, Some(900));
        assert_eq!(fire_at, now + chrono::Duration::seconds(900));
    }

    #[test]
    fn parse_when_short_form() {
        let now = fixed_now();
        let (fire_at, interval) = parse_when_str("2h", now).unwrap();
        assert_eq!(interval, Some(7200));
        assert_eq!(fire_at, now + chrono::Duration::seconds(7200));
    }

    #[test]
    fn parse_when_iso8601() {
        let now = fixed_now();
        let (fire_at, interval) = parse_when_str("2026-05-15T12:00:00Z", now).unwrap();
        assert_eq!(interval, None);
        let expected = Utc.with_ymd_and_hms(2026, 5, 15, 12, 0, 0).unwrap();
        assert_eq!(fire_at, expected);
    }

    #[test]
    fn parse_when_invalid_returns_err() {
        let now = fixed_now();
        assert!(parse_when_str("next Tuesday", now).is_err());
    }

    // ── ScheduledTimerStore ───────────────────────────────────────────────────

    fn make_timer(id: &str, fire_at: DateTime<Utc>) -> ScheduledTimer {
        ScheduledTimer {
            id: id.to_string(),
            label: None,
            fire_at,
            action: TimerAction::Prompt {
                text: "test".to_string(),
            },
            mode: TimerMode::Once,
            created_at: Utc::now(),
        }
    }

    #[test]
    fn store_empty_on_missing_file() {
        let dir = TempDir::new().unwrap();
        let store = ScheduledTimerStore::load(dir.path().join("timers.json"));
        assert!(store.list().is_empty());
    }

    #[test]
    fn store_add_and_list() {
        let dir = TempDir::new().unwrap();
        let store = ScheduledTimerStore::load(dir.path().join("timers.json"));
        let t = Utc::now() + chrono::Duration::hours(1);
        store.add(make_timer("tm-aabbccdd", t)).unwrap();
        let list = store.list();
        assert_eq!(list.len(), 1);
        assert_eq!(list[0].id, "tm-aabbccdd");
    }

    #[test]
    fn store_add_duplicate_id_fails() {
        let dir = TempDir::new().unwrap();
        let store = ScheduledTimerStore::load(dir.path().join("timers.json"));
        let t = Utc::now() + chrono::Duration::hours(1);
        store.add(make_timer("tm-aabbccdd", t)).unwrap();
        assert!(store.add(make_timer("tm-aabbccdd", t)).is_err());
    }

    #[test]
    fn store_remove_by_id() {
        let dir = TempDir::new().unwrap();
        let store = ScheduledTimerStore::load(dir.path().join("timers.json"));
        let t = Utc::now() + chrono::Duration::hours(1);
        store.add(make_timer("tm-aabbccdd", t)).unwrap();
        assert!(store.remove_by_id("tm-aabbccdd"));
        assert!(!store.remove_by_id("tm-aabbccdd"));
        assert!(store.list().is_empty());
    }

    #[test]
    fn store_persists_and_reloads() {
        let dir = TempDir::new().unwrap();
        let path = dir.path().join("timers.json");
        let t = Utc::now() + chrono::Duration::hours(2);
        {
            let store = ScheduledTimerStore::load(path.clone());
            store.add(make_timer("tm-aabbccdd", t)).unwrap();
        }
        let store2 = ScheduledTimerStore::load(path);
        assert_eq!(store2.list().len(), 1);
        assert_eq!(store2.list()[0].id, "tm-aabbccdd");
    }

    #[test]
    fn take_due_returns_only_past_entries() {
        let dir = TempDir::new().unwrap();
        let store = ScheduledTimerStore::load(dir.path().join("timers.json"));
        let past = Utc::now() - chrono::Duration::minutes(1);
        let future = Utc::now() + chrono::Duration::hours(1);
        store.add(make_timer("tm-past", past)).unwrap();
        store.add(make_timer("tm-future", future)).unwrap();

        let due = store.take_due(Utc::now());
        assert_eq!(due.len(), 1);
        assert_eq!(due[0].id, "tm-past");
        assert_eq!(store.list().len(), 1);
        assert_eq!(store.list()[0].id, "tm-future");
    }

    #[test]
    fn take_due_with_already_past_fires_immediately() {
        let dir = TempDir::new().unwrap();
        let store = ScheduledTimerStore::load(dir.path().join("timers.json"));
        // Simulate server restart: timer scheduled in past (catch-up semantics)
        let way_past = Utc::now() - chrono::Duration::hours(3);
        store.add(make_timer("tm-catchup", way_past)).unwrap();
        let due = store.take_due(Utc::now());
        assert_eq!(due.len(), 1, "past timer must fire on next tick");
    }

    #[test]
    fn new_id_has_tm_prefix() {
        let id = ScheduledTimer::new_id();
        assert!(id.starts_with("tm-"), "expected 'tm-' prefix: {id}");
        assert_eq!(id.len(), 11, "expected 'tm-' + 8 hex chars: {id}");
    }

    // ── TimerAction serde ─────────────────────────────────────────────────────

    #[test]
    fn timer_action_mcp_round_trips() {
        let action = TimerAction::Mcp {
            method: "start_agent".to_string(),
            args: serde_json::json!({ "story_id": "42_foo" }),
        };
        let s = serde_json::to_string(&action).unwrap();
        let back: TimerAction = serde_json::from_str(&s).unwrap();
        assert_eq!(action, back);
    }

    #[test]
    fn timer_action_prompt_round_trips() {
        let action = TimerAction::Prompt {
            text: "daily standup reminder".to_string(),
        };
        let s = serde_json::to_string(&action).unwrap();
        let back: TimerAction = serde_json::from_str(&s).unwrap();
        assert_eq!(action, back);
    }

    // ── TimerMode serde ───────────────────────────────────────────────────────

    #[test]
    fn timer_mode_once_round_trips() {
        let mode = TimerMode::Once;
        let s = serde_json::to_string(&mode).unwrap();
        let back: TimerMode = serde_json::from_str(&s).unwrap();
        assert_eq!(mode, back);
    }

    #[test]
    fn timer_mode_recurring_round_trips() {
        let mode = TimerMode::Recurring {
            interval_secs: 3600,
        };
        let s = serde_json::to_string(&mode).unwrap();
        let back: TimerMode = serde_json::from_str(&s).unwrap();
        assert_eq!(mode, back);
    }
}