Lutra/crates/terminal/src/lib.rs
danny a8daf269fb M3.6: integrated terminal with PTY sessions and xterm.js sub-tabs
- crates/terminal: portable-pty sessions (ConPTY on Windows) with reader,
  writer and waiter threads, UTF-8 chunking, a 1 MiB output buffer with
  backpressure, a non-blocking input queue, resize, kill and exit codes;
  default shell pwsh -> powershell -> cmd on Windows, $SHELL or /bin/sh.
- Engine: terminal.create/input/resize/close, terminalOutput (capped per
  terminal and per pump, round-robin) and terminalExited through the pump;
  terminals close with the project and on app.quit.
- UI: Terminal tab in the bottom panel (tabs next to Find), xterm.js with
  the fit addon, sub-tabs, copy/paste, a focus rule that leaves plain Ctrl
  keys to the shell, terminal.open (Mod+Shift+T), --lt-terminal-* ANSI
  tokens in both themes (text colours AA) and a 4.5:1 minimum contrast.
- Tests: real-shell crate tests (UTF-8, backpressure), engine and TCP
  control tests, Vitest with a mocked xterm; live check on port 7936;
  docs and parity rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 21:10:37 +02:00

68 lines
2.8 KiB
Rust

//! Integrated terminal sessions for Lutra (layer L3).
//!
//! Spawns shells in pseudo-terminals (`portable-pty`: ConPTY on Windows, a
//! Unix pty elsewhere) and hands their output to the engine, which streams
//! it to the frontend, where xterm.js renders it.
//!
//! A [`Session`] owns three threads, so that no call on it blocks its
//! caller (the engine holds its lock while it calls in):
//!
//! - the **reader** reads the pty, decodes UTF-8 with [`Utf8Chunker`]
//! (a multibyte character split across two reads is joined, invalid
//! bytes become U+FFFD) and appends the text to a bounded output buffer;
//! - the **writer** writes queued input to the pty;
//! - the **waiter** waits for the shell to exit, records the exit code and
//! closes the pty, which ends the reader (ConPTY only reports end of
//! output once the pseudo console is closed).
//!
//! **Output buffer and drop policy:** each session buffers at most
//! [`OUTPUT_CAP`] bytes of decoded text. When the buffer is full the reader
//! stops reading, so the shell blocks on its next write (backpressure, as in
//! a real terminal): output is never dropped while the session runs. Output
//! still buffered when the session is closed or killed is dropped.
//! [`Session::take_output`] drains the buffer in pieces of a size the caller
//! chooses, cut on character boundaries.
//!
//! **Input:** [`Session::write`] queues input for the writer thread; at most
//! [`INPUT_QUEUE_CHUNKS`] pieces of up to [`INPUT_CHUNK`] bytes wait. A full
//! queue refuses more input ([`TerminalError::InputFull`]) instead of
//! blocking.
//!
//! **Exit:** [`Session::exit`] reports the exit code once the shell exited
//! and its output was read to the end (or [`EXIT_GRACE`] passed, for a
//! background process that keeps the pty open) and drained.
mod session;
mod shell;
mod utf8;
pub use session::{
EXIT_GRACE, Exit, INPUT_CHUNK, INPUT_QUEUE_CHUNKS, MAX_SIZE, OUTPUT_CAP, Session, SpawnOptions,
};
pub use shell::{Shell, default_shell, find_in_path};
pub use utf8::Utf8Chunker;
/// Errors of terminal sessions.
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum TerminalError {
/// The pseudo terminal could not be created or the shell not started.
#[error("cannot start the terminal: {0}")]
Spawn(String),
/// Resizing the pseudo terminal failed.
#[error("cannot resize the terminal: {0}")]
Resize(String),
/// A size outside `1..=MAX_SIZE` columns or rows.
#[error("invalid terminal size {cols}x{rows}")]
InvalidSize {
/// Requested columns.
cols: u16,
/// Requested rows.
rows: u16,
},
/// The input queue is full; the shell is not reading its input.
#[error("the terminal is not reading its input")]
InputFull,
/// The session has ended; it takes no more input or resizes.
#[error("the terminal has exited")]
Exited,
}