Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

4.0 KB
Raw Blame
//! Terminal setup / teardown with panic-safe restoration.
//!
//! Owning the terminal means switching to the alternate screen and enabling raw
//! mode; both **must** be undone on every exit path — normal return, `?`
//! propagation, and panic — or the user's shell is left in a broken state
//! (no echo, no line editing, stuck on the alternate screen). [`TerminalGuard`]
//! restores on `Drop`, and [`install_panic_hook`] chains a restore ahead of the
//! previous panic hook so the panic message prints to a sane terminal.

use std::io::{self, Stdout};

use crossterm::event::{
    DisableBracketedPaste, DisableMouseCapture, EnableBracketedPaste, EnableMouseCapture,
};
use crossterm::execute;
use crossterm::terminal::{
    disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
};
use ratatui::backend::CrosstermBackend;
use ratatui::Terminal;

/// The concrete ratatui terminal type used by the TUI.
pub type Tui = Terminal<CrosstermBackend<Stdout>>;

/// RAII guard that enters the alternate screen + raw mode on construction and
/// restores the terminal on drop.
pub struct TerminalGuard {
    terminal: Tui,
    alternate_screen: bool,
    mouse: bool,
}

impl TerminalGuard {
    pub fn enter_with_options(alternate_screen: bool) -> io::Result<Self> {
        install_panic_hook(alternate_screen);
        enable_raw_mode()?;
        let mut stdout = io::stdout();
        if alternate_screen {
            execute!(
                stdout,
                EnterAlternateScreen,
                EnableMouseCapture,
                EnableBracketedPaste
            )?;
        } else {
            execute!(stdout, EnableBracketedPaste)?;
        }
        let backend = CrosstermBackend::new(io::stdout());
        let terminal = Terminal::new(backend)?;
        log::debug!("[tui] terminal: entered alternate screen + raw mode");
        Ok(Self {
            terminal,
            alternate_screen,
            mouse: alternate_screen,
        })
    }

    /// Mutable access to the underlying terminal for drawing.
    pub fn terminal(&mut self) -> &mut Tui {
        &mut self.terminal
    }
    pub fn set_mouse(&mut self, enabled: bool) -> io::Result<()> {
        if self.mouse != enabled {
            if enabled {
                execute!(io::stdout(), EnableMouseCapture)?;
            } else {
                execute!(io::stdout(), DisableMouseCapture)?;
            }
            self.mouse = enabled;
        }
        Ok(())
    }
}

impl Drop for TerminalGuard {
    fn drop(&mut self) {
        if let Err(e) = restore(self.alternate_screen) {
            // The subscriber writes to a file (never the terminal), so this is
            // safe to log here.
            log::warn!("[tui] terminal: restore on drop failed: {e}");
        } else {
            log::debug!("[tui] terminal: restored on drop");
        }
    }
}

/// Undo everything [`TerminalGuard::enter`] did. Best-effort — each step is
/// attempted even if an earlier one fails, so a partial setup still gets torn
/// down as far as possible.
fn restore(alternate_screen: bool) -> io::Result<()> {
    let mut stdout = io::stdout();
    if alternate_screen {
        let _ = execute!(
            stdout,
            DisableBracketedPaste,
            LeaveAlternateScreen,
            DisableMouseCapture
        );
    } else {
        let _ = execute!(stdout, DisableBracketedPaste);
    }
    disable_raw_mode()
}

/// Chain a terminal-restoring step in front of the process panic hook, so a
/// panic inside the render loop leaves the user with a usable terminal and a
/// readable backtrace instead of a garbled alternate screen.
///
/// Idempotent in effect: called once from [`TerminalGuard::enter`]. If it were
/// ever called twice, the second restore would simply be a no-op on an
/// already-restored terminal.
fn install_panic_hook(alternate_screen: bool) {
    let original = std::panic::take_hook();
    std::panic::set_hook(Box::new(move |info| {
        let _ = restore(alternate_screen);
        original(info);
    }));
}