mecha10_cli/dev/

termination.rs

//! Shared termination/intent model for `mecha10 dev`'s interactive TUI screens.
//!
//! Before this module existed, "what does this key mean" was answered independently by every
//! screen that owned terminal input: the outer dev-mode loop (`ops/interactive.rs`) had its own
//! `is_dev_quit_key`, the teleop sub-screen (`ui/teleop.rs`) had its own `is_quit_all_key` plus a
//! separate zero-velocity `x`/Space branch, and three more call sites each registered their own
//! `ctrlc::set_handler`. Because those handlers didn't compose, the same physical key (`x`) meant
//! two unrelated things depending on which screen happened to own input at the time: "stop the
//! simulation" at the outer dev-mode menu, or "zero velocity, stay put" inside teleop. A user who
//! pressed `s` (enter simulation, which auto-opens teleop) then `x` got the second meaning and
//! nothing stopped - the reported bug this module fixes.
//!
//! `classify_key` gives every screen the same answer for "what does this key mean", and
//! `ScreenOutcome` lets a nested screen (teleop) report what happened without needing to know
//! about the outer loop's own shutdown flag - the translation from "screen backed out" to "what
//! that means for this caller" belongs to the caller (see `ops/teleop.rs::enter_teleop_mode`),
//! not to the screen itself.
//!
//! `install_quit_signal` replaces the four independent, copy-pasted `ctrlc::set_handler`
//! registrations (`ops/interactive.rs`, `ops/lifecycle.rs::run_watch_mode`,
//! `handlers/logs.rs::follow_logs`, plus what used to be `ui/teleop.rs`'s own Ctrl+C handling
//! before it was folded into `classify_key`) with one shared helper.

use anyhow::Result;
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, OnceLock};

/// What a termination-shaped key ("stop the current thing" or "quit everything") means.
///
/// Deliberately does not cover Space - Space is "zero velocity, stay in teleop", a distinct
/// non-terminating safety control, not a termination concept. It never goes through
/// `classify_key` at all; see `ui/teleop.rs::handle_key`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TerminationIntent {
    /// Stop whatever the current active mode/screen is driving, and return to its parent
    /// context. Bare `q`, `Esc`, or bare `x` (no modifiers).
    StopCurrent,
    /// Tear down the entire `mecha10 dev` session - every running node, every nested screen.
    /// Ctrl+C or Ctrl+X.
    QuitAll,
}

/// Classify a key event into a `TerminationIntent`, if it is one. Pure, dependency-free function
/// so it's unit testable without a live terminal/event loop.
///
/// - Bare `q` / `Esc` / bare `x` (no modifiers) -> `StopCurrent`.
/// - Ctrl+C / Ctrl+X (any other modifiers alongside Control, e.g. Shift from a capital-C keycap,
///   still match - `contains` rather than exact equality) -> `QuitAll`.
/// - Anything else (including Space, and `q`/`x` with unrelated modifiers) -> `None`.
pub fn classify_key(key: &KeyEvent) -> Option<TerminationIntent> {
    if key.modifiers.contains(KeyModifiers::CONTROL) && matches!(key.code, KeyCode::Char('c') | KeyCode::Char('x')) {
        return Some(TerminationIntent::QuitAll);
    }

    if key.modifiers.is_empty() && matches!(key.code, KeyCode::Char('q') | KeyCode::Esc | KeyCode::Char('x')) {
        return Some(TerminationIntent::StopCurrent);
    }

    None
}

/// What a nested screen's event loop did, for its caller to interpret. A screen that owns its own
/// sub-context (e.g. `TeleopUi`) should never mutate the outer loop's shutdown flag directly - it
/// reports what happened here, and lets the caller (which knows how it was entered) decide what
/// that means. See `ops/teleop.rs::enter_teleop_mode`, which interprets `ReturnToParent`
/// differently depending on whether it was entered via `'s'` (simulation hand-off, so backing out
/// means "stop the simulation and return to the dev-mode menu") or `'t'` (standalone teleop, so
/// backing out just closes the screen).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScreenOutcome {
    /// `TerminationIntent::StopCurrent` fired, or the screen's own back-out (e.g. `q`/Esc)
    /// completed normally.
    ReturnToParent,
    /// `TerminationIntent::QuitAll` fired - propagate outward unswallowed, all the way to the
    /// top-level `running` flag, so the outer loop's own `if !running.load() { break }` handles
    /// full session teardown.
    QuitAll,
    /// Nothing terminal happened; keep running the screen's event loop.
    Continue,
}

/// Guards against `ctrlc::set_handler`'s "can only be installed once per process" restriction.
/// Safe here because `install_quit_signal`'s call sites are mutually exclusive invocation paths
/// within one process lifetime (e.g. `mecha10 dev` vs `mecha10 dev --watch` vs `mecha10 logs -f`
/// never run concurrently in the same process) - this is a defensive guard, not a concurrency
/// mechanism.
static QUIT_SIGNAL_INSTALLED: OnceLock<Arc<AtomicBool>> = OnceLock::new();

/// Serializes the check-then-register sequence in `install_quit_signal` so two concurrent
/// callers (e.g. tests running in parallel within the same process) can't both observe
/// `QUIT_SIGNAL_INSTALLED` as empty and both call `ctrlc::set_handler`, which errors on its
/// second invocation. Without this, `install_quit_signal` had a TOCTOU race: the read of
/// `QUIT_SIGNAL_INSTALLED.get()` and the write via `get_or_init` weren't atomic with the
/// `ctrlc::set_handler` call in between, so the loser of the race returned an error instead of
/// the winner's shared flag.
static QUIT_SIGNAL_INIT_LOCK: Mutex<()> = Mutex::new(());

/// Install a single process-wide Ctrl+C handler and return the shared "keep running" flag it
/// clears on signal. Replaces the four independent, copy-pasted `ctrlc::set_handler`
/// registrations that used to exist across `ops/interactive.rs`, `ops/lifecycle.rs`, and
/// `handlers/logs.rs`.
///
/// Calling this more than once within a process is safe: only the first call actually registers
/// the OS-level handler; subsequent (and concurrent) calls just return the same shared
/// `AtomicBool`, since `ctrlc::set_handler` itself can only be installed once and would error on
/// a second registration attempt. The registration itself is serialized by
/// `QUIT_SIGNAL_INIT_LOCK` so concurrent first-callers can't race each other into that error.
pub fn install_quit_signal() -> Result<Arc<AtomicBool>> {
    if let Some(existing) = QUIT_SIGNAL_INSTALLED.get() {
        return Ok(existing.clone());
    }

    let _guard = QUIT_SIGNAL_INIT_LOCK
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner());

    if let Some(existing) = QUIT_SIGNAL_INSTALLED.get() {
        return Ok(existing.clone());
    }

    let running = Arc::new(AtomicBool::new(true));
    let r = running.clone();
    ctrlc::set_handler(move || {
        r.store(false, Ordering::SeqCst);
    })?;

    Ok(QUIT_SIGNAL_INSTALLED.get_or_init(|| running).clone())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crossterm::event::KeyEvent;

    #[test]
    fn plain_q_is_stop_current() {
        let key = KeyEvent::new(KeyCode::Char('q'), KeyModifiers::NONE);
        assert_eq!(classify_key(&key), Some(TerminationIntent::StopCurrent));
    }

    #[test]
    fn esc_is_stop_current() {
        let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
        assert_eq!(classify_key(&key), Some(TerminationIntent::StopCurrent));
    }

    #[test]
    fn plain_x_without_control_modifier_is_stop_current() {
        let key = KeyEvent::new(KeyCode::Char('x'), KeyModifiers::NONE);
        assert_eq!(classify_key(&key), Some(TerminationIntent::StopCurrent));
    }

    #[test]
    fn ctrl_c_is_quit_all() {
        let key = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL);
        assert_eq!(classify_key(&key), Some(TerminationIntent::QuitAll));
    }

    #[test]
    fn ctrl_x_is_quit_all() {
        let key = KeyEvent::new(KeyCode::Char('x'), KeyModifiers::CONTROL);
        assert_eq!(classify_key(&key), Some(TerminationIntent::QuitAll));
    }

    #[test]
    fn ctrl_shift_c_is_still_quit_all() {
        let key = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL | KeyModifiers::SHIFT);
        assert_eq!(classify_key(&key), Some(TerminationIntent::QuitAll));
    }

    #[test]
    fn space_is_not_a_termination_key() {
        let key = KeyEvent::new(KeyCode::Char(' '), KeyModifiers::NONE);
        assert_eq!(classify_key(&key), None);
    }

    #[test]
    fn plain_c_without_control_modifier_is_not_a_termination_key() {
        let key = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::NONE);
        assert_eq!(classify_key(&key), None);
    }

    #[test]
    fn ctrl_q_is_not_a_termination_key() {
        let key = KeyEvent::new(KeyCode::Char('q'), KeyModifiers::CONTROL);
        assert_eq!(classify_key(&key), None);
    }

    #[test]
    fn unrelated_key_is_not_a_termination_key() {
        let key = KeyEvent::new(KeyCode::Char('w'), KeyModifiers::NONE);
        assert_eq!(classify_key(&key), None);
    }

    #[test]
    fn install_quit_signal_returns_a_flag_initially_true() {
        let running = install_quit_signal().expect("installing the quit signal must succeed");
        assert!(running.load(Ordering::SeqCst));
    }

    #[test]
    fn install_quit_signal_is_idempotent_across_repeated_calls() {
        let first = install_quit_signal().expect("first install must succeed");
        let second = install_quit_signal().expect("second install must not error");
        assert!(Arc::ptr_eq(&first, &second));
    }

    #[test]
    fn install_quit_signal_survives_concurrent_first_callers() {
        let handles: Vec<_> = (0..16).map(|_| std::thread::spawn(install_quit_signal)).collect();

        let flags: Vec<Arc<AtomicBool>> = handles
            .into_iter()
            .map(|handle| {
                handle
                    .join()
                    .expect("thread must not panic")
                    .expect("install_quit_signal must not error")
            })
            .collect();

        let first = &flags[0];
        for flag in &flags[1..] {
            assert!(
                Arc::ptr_eq(first, flag),
                "all concurrent callers must observe the same shared flag"
            );
        }
    }
}