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>
This commit is contained in:
danny 2026-10-18 11:25:30 +02:00
parent 5fa7f0c8b3
commit a8daf269fb
45 changed files with 3935 additions and 49 deletions

View file

@ -47,7 +47,8 @@ impl Command for Quit {
}
}
fn run(&self, _state: &mut State, _params: Value) -> Result<Outcome, EngineError> {
fn run(&self, state: &mut State, _params: Value) -> Result<Outcome, EngineError> {
crate::cmd::terminal::close_all(state);
Ok(Outcome::effect(Effect::Quit))
}
}

View file

@ -10,6 +10,7 @@ mod recovery;
pub mod search;
mod settings;
pub mod syntax;
pub mod terminal;
pub mod theme;
pub mod toolchain;
pub mod ui;
@ -53,5 +54,9 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> {
registry.register(Box::new(toolchain::Status))?;
registry.register(Box::new(toolchain::DownloadPhpactor))?;
registry.register(Box::new(buffer::List))?;
registry.register(Box::new(terminal::Create))?;
registry.register(Box::new(terminal::Input))?;
registry.register(Box::new(terminal::Resize))?;
registry.register(Box::new(terminal::Close))?;
Ok(())
}

View file

@ -0,0 +1,437 @@
//! The integrated terminal: `terminal.create`, `terminal.input`,
//! `terminal.resize` and `terminal.close`, and the events
//! `terminalOutput` and `terminalExited`.
//!
//! Each terminal is a [`lutra_terminal::Session`]: a shell in a pseudo
//! terminal whose reading, writing and waiting happen on threads of its own,
//! so no command blocks the engine lock on the shell. Output waits in the
//! session's bounded buffer (backpressure when full, see the crate) until
//! [`crate::Engine::pump_vfs`] calls [`pump`], which emits one
//! `terminalOutput` per terminal with at most [`MAX_OUTPUT_PER_TERMINAL`]
//! bytes, at most [`MAX_OUTPUT_PER_PUMP`] bytes over all terminals
//! (round-robin, so one busy terminal cannot starve the others). With the
//! desktop's pump every 100 ms that caps the stream at about 2.5 MB/s; the
//! shell waits when it writes faster. `terminalExited` follows the last
//! output of a shell that ended.
//!
//! Terminals belong to the project open when they were created: closing the
//! project (or opening another) closes them ([`sync_project`], run after
//! every command and every pump), and so does `app.quit` ([`close_all`]).
//! A terminal closed by Lutra reports `terminalExited` with `code: null`.
use std::collections::BTreeMap;
use std::ops::Bound;
use std::path::{Path, PathBuf};
use lutra_terminal::{Session, Shell, SpawnOptions, TerminalError};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use crate::cmd::params::parse;
use crate::{Command, CommandSpec, EngineError, Event, Outcome, State};
/// Most terminals open at once.
pub const MAX_TERMINALS: usize = 16;
/// Most bytes of input one `terminal.input` takes.
pub const MAX_INPUT_BYTES: usize = 1 << 20;
/// Most bytes of output one pump emits for one terminal.
pub const MAX_OUTPUT_PER_TERMINAL: usize = 64 * 1024;
/// Most bytes of output one pump emits over all terminals.
pub const MAX_OUTPUT_PER_PUMP: usize = 256 * 1024;
/// Events of the terminal, appended to [`Event`] untagged: each serialises
/// with its own `kind`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(
tag = "kind",
rename_all = "camelCase",
rename_all_fields = "camelCase"
)]
pub enum TerminalEvent {
/// Output of a terminal, as UTF-8 text with the shell's escape
/// sequences; at most [`MAX_OUTPUT_PER_TERMINAL`] bytes.
TerminalOutput {
/// The terminal, as `terminal.create` returned it.
terminal_id: u64,
/// The text; never empty.
data: String,
},
/// A terminal ended: its shell exited or Lutra closed it. No events for
/// it follow.
TerminalExited {
/// The terminal.
terminal_id: u64,
/// The shell's exit code; `null` when Lutra closed the terminal or
/// the code is unknown.
code: Option<i64>,
},
}
/// The open terminals.
#[derive(Debug, Default)]
pub struct Terminals {
/// The id of the last terminal created; ids are never reused.
last_id: u64,
/// The terminal the last pump emitted output for first; the next pump
/// starts after it.
cursor: u64,
/// Open terminals by id.
sessions: BTreeMap<u64, Running>,
}
impl Terminals {
/// Number of open terminals.
pub fn len(&self) -> usize {
self.sessions.len()
}
/// Whether no terminal is open.
pub fn is_empty(&self) -> bool {
self.sessions.is_empty()
}
}
/// One open terminal.
#[derive(Debug)]
struct Running {
/// The shell.
session: Session,
/// Root of the project it belongs to.
root: PathBuf,
}
/// Root of the open project.
fn project_root(state: &State) -> Option<PathBuf> {
state
.project
.as_ref()
.map(|w| w.project.root().to_path_buf())
}
/// An engine error for a session error of command `id`.
fn session_error(id: &str, e: TerminalError) -> EngineError {
match e {
TerminalError::InvalidSize { .. } => EngineError::invalid_params(id, e.to_string()),
_ => EngineError::Failed(e.to_string()),
}
}
/// The open terminal `terminal_id`.
fn running<'a>(state: &'a State, id: &str, terminal_id: u64) -> Result<&'a Running, EngineError> {
state
.terminals
.sessions
.get(&terminal_id)
.ok_or_else(|| EngineError::invalid_params(id, format!("no terminal {terminal_id}")))
}
/// Params of `terminal.create`.
#[derive(Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct CreateParams {
/// Working directory: project-relative or absolute.
cwd: Option<String>,
/// Program to run instead of the default shell.
shell: Option<String>,
/// Columns.
cols: u16,
/// Rows.
rows: u16,
}
/// `terminal.create`: starts a shell in a new terminal.
pub struct Create;
impl Command for Create {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "terminal.create",
label: "New Terminal",
menu_path: None,
default_shortcut: None,
params: "{ cwd? (project-relative or absolute directory, default the project root), shell? (program name or path; default pwsh, then powershell, then cmd on Windows, $SHELL or /bin/sh elsewhere), cols, rows (1..=1000) }; returns { terminalId }, then events terminalOutput { terminalId, data } and terminalExited { terminalId, code }; at most 16 terminals",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let id = self.spec().id;
let p: CreateParams = parse(id, params)?;
if state.terminals.sessions.len() >= MAX_TERMINALS {
return Err(EngineError::Failed(format!(
"at most {MAX_TERMINALS} terminals can be open"
)));
}
let root = project_root(state).ok_or_else(|| EngineError::Disabled(id.to_string()))?;
let cwd = match p.cwd.as_deref() {
None | Some("") => root.clone(),
Some(dir) => root.join(Path::new(dir)),
};
if !cwd.is_dir() {
return Err(EngineError::invalid_params(
id,
format!("{} is not a directory", cwd.display()),
));
}
let shell = match p.shell.as_deref() {
None | Some("") => lutra_terminal::default_shell(),
Some(program) => Shell::new(
lutra_terminal::find_in_path(program).unwrap_or_else(|| PathBuf::from(program)),
),
};
let session = Session::spawn(SpawnOptions {
shell,
cwd,
cols: p.cols,
rows: p.rows,
env: Vec::new(),
})
.map_err(|e| session_error(id, e))?;
let terminals = &mut state.terminals;
terminals.last_id = terminals.last_id.saturating_add(1);
let terminal_id = terminals.last_id;
terminals
.sessions
.insert(terminal_id, Running { session, root });
Ok(Outcome::value(json!({ "terminalId": terminal_id })))
}
}
/// Params of `terminal.input`.
#[derive(Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct InputParams {
/// The terminal.
terminal_id: u64,
/// Keys or pasted text, as xterm.js sends them.
data: String,
}
/// `terminal.input`: sends input to a terminal's shell.
pub struct Input;
impl Command for Input {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "terminal.input",
label: "Terminal Input",
menu_path: None,
default_shortcut: None,
params: "{ terminalId, data (at most 1 MiB) }; returns null; failed when the shell has exited or is not reading its input",
}
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let id = self.spec().id;
let p: InputParams = parse(id, params)?;
if p.data.len() > MAX_INPUT_BYTES {
return Err(EngineError::invalid_params(
id,
format!("at most {MAX_INPUT_BYTES} bytes of input per call"),
));
}
running(state, id, p.terminal_id)?
.session
.write(p.data.as_bytes())
.map_err(|e| session_error(id, e))?;
Ok(Outcome::default())
}
}
/// Params of `terminal.resize`.
#[derive(Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct ResizeParams {
/// The terminal.
terminal_id: u64,
/// Columns.
cols: u16,
/// Rows.
rows: u16,
}
/// `terminal.resize`: changes a terminal's size.
pub struct Resize;
impl Command for Resize {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "terminal.resize",
label: "Resize Terminal",
menu_path: None,
default_shortcut: None,
params: "{ terminalId, cols, rows (1..=1000) }; returns null",
}
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let id = self.spec().id;
let p: ResizeParams = parse(id, params)?;
running(state, id, p.terminal_id)?
.session
.resize(p.cols, p.rows)
.map_err(|e| session_error(id, e))?;
Ok(Outcome::default())
}
}
/// Params of `terminal.close`.
#[derive(Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
struct CloseParams {
/// The terminal.
terminal_id: u64,
}
/// `terminal.close`: kills a terminal's shell.
pub struct Close;
impl Command for Close {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "terminal.close",
label: "Close Terminal",
menu_path: None,
default_shortcut: None,
params: "{ terminalId }; returns { closed }: false if the terminal already ended; a closed terminal reports terminalExited { code: null }",
}
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let p: CloseParams = parse(self.spec().id, params)?;
let closed = close(state, p.terminal_id);
Ok(Outcome::value(json!({ "closed": closed })))
}
}
/// Kills terminal `terminal_id`, drops its buffered output and emits
/// `terminalExited {code: null}`.
///
/// # Returns
/// Whether the terminal was open.
fn close(state: &mut State, terminal_id: u64) -> bool {
let Some(mut running) = state.terminals.sessions.remove(&terminal_id) else {
return false;
};
running.session.kill();
state.emit(Event::Terminal(TerminalEvent::TerminalExited {
terminal_id,
code: None,
}));
true
}
/// Closes every terminal, for `app.quit`.
pub fn close_all(state: &mut State) {
let ids: Vec<u64> = state.terminals.sessions.keys().copied().collect();
for terminal_id in ids {
close(state, terminal_id);
}
}
/// Closes the terminals of a project that is no longer open.
pub fn sync_project(state: &mut State) {
let root = project_root(state);
let stale: Vec<u64> = state
.terminals
.sessions
.iter()
.filter(|(_, r)| root.as_ref() != Some(&r.root))
.map(|(&id, _)| id)
.collect();
for terminal_id in stale {
close(state, terminal_id);
}
}
/// Moves buffered output into `terminalOutput` events and reports ended
/// shells with `terminalExited`; see the module documentation for the caps.
/// Closes the terminals of a project that is no longer open first.
pub fn pump(state: &mut State) {
sync_project(state);
let terminals = &mut state.terminals;
let cursor = terminals.cursor;
let order: Vec<u64> = terminals
.sessions
.range((Bound::Excluded(cursor), Bound::Unbounded))
.chain(terminals.sessions.range(..=cursor))
.map(|(&id, _)| id)
.collect();
let mut budget = MAX_OUTPUT_PER_PUMP;
let mut events = Vec::new();
let mut ended = Vec::new();
let mut first = None;
for terminal_id in order {
let Some(running) = terminals.sessions.get(&terminal_id) else {
continue;
};
if budget > 0 {
let data = running
.session
.take_output(budget.min(MAX_OUTPUT_PER_TERMINAL));
if !data.is_empty() {
budget = budget.saturating_sub(data.len());
first.get_or_insert(terminal_id);
events.push(TerminalEvent::TerminalOutput { terminal_id, data });
}
}
if let Some(exit) = running.session.exit() {
events.push(TerminalEvent::TerminalExited {
terminal_id,
code: exit.code,
});
ended.push(terminal_id);
}
}
if let Some(first) = first {
terminals.cursor = first;
}
for terminal_id in ended {
terminals.sessions.remove(&terminal_id);
}
for event in events {
state.emit(Event::Terminal(event));
}
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::TerminalEvent;
use crate::Event;
#[test]
fn event_shapes() {
let e = Event::Terminal(TerminalEvent::TerminalOutput {
terminal_id: 1,
data: "hi\r\n".into(),
});
assert_eq!(
serde_json::to_value(e).unwrap(),
json!({"kind": "terminalOutput", "terminalId": 1, "data": "hi\r\n"})
);
let e = Event::Terminal(TerminalEvent::TerminalExited {
terminal_id: 1,
code: Some(3),
});
assert_eq!(
serde_json::to_value(e).unwrap(),
json!({"kind": "terminalExited", "terminalId": 1, "code": 3})
);
let e = Event::Terminal(TerminalEvent::TerminalExited {
terminal_id: 2,
code: None,
});
assert_eq!(
serde_json::to_value(e).unwrap(),
json!({"kind": "terminalExited", "terminalId": 2, "code": null})
);
}
}

View file

@ -119,6 +119,7 @@ impl Engine {
}
let outcome = command.run(state, params);
crate::workspace::sync_buffer_dirs(state);
cmd::terminal::sync_project(state);
outcome
});
state.commands_run = state.commands_run.saturating_add(1);
@ -134,6 +135,7 @@ impl Engine {
/// events (see [`cmd::search`]), merges index updates (see
/// [`cmd::goto`]), stores finished parses and starts due ones (see
/// [`cmd::syntax`]) and returns every queued event.
/// Terminal output and exits become events too (see [`cmd::terminal`]).
/// Hosts call it regularly, e.g. every 100 ms from a background thread.
///
/// # Errors
@ -148,6 +150,7 @@ impl Engine {
cmd::goto::sync(state);
cmd::syntax::pump(state, std::time::Instant::now());
cmd::toolchain::pump(state);
cmd::terminal::pump(state);
Ok(())
})?;
Ok(state.take_events())
@ -410,6 +413,10 @@ mod tests {
"settings.reset",
"settings.set",
"syntax.outline",
"terminal.close",
"terminal.create",
"terminal.input",
"terminal.resize",
"test.disabled",
"theme.list",
"theme.systemPreference",

View file

@ -197,6 +197,9 @@ pub enum Event {
/// PHP or Phpactor changed: `{php, phpactor}` as `toolchain.status`
/// returns it.
ToolchainChanged(crate::cmd::toolchain::ToolchainStatus),
/// Terminal events (`terminalOutput`, `terminalExited`), see [`crate::cmd::terminal`].
#[serde(untagged)]
Terminal(crate::cmd::terminal::TerminalEvent),
}
/// One match of [`Event::SearchResults`]. Positions are 0-based; columns

View file

@ -43,6 +43,8 @@ pub struct State {
pub syntax: crate::cmd::syntax::Syntax,
/// PHP and Phpactor (`toolchain.status`).
pub toolchain: crate::cmd::toolchain::Toolchain,
/// Open integrated terminals (`terminal.*`).
pub terminals: crate::cmd::terminal::Terminals,
/// Number of notifications emitted, for their ids.
notifications: u64,
/// Events queued for the host, oldest first.

View file

@ -62,6 +62,35 @@ pub const SYNTAX_TOKENS: &[&str] = &[
"operator",
];
/// Terminal token names (`--lt-terminal-<name>`) every theme defines: the
/// terminal's background, text, cursor and selection, and the 16 ANSI
/// colours xterm.js maps escape sequences to. Every ANSI colour that shows
/// as text reaches 4.5:1 on `terminal-bg` (`ui/tests/theme/contrast.test.ts`);
/// the exceptions are the colour meant to vanish into the background: ANSI
/// black in the dark theme, white and bright white in the light one.
pub const TERMINAL_TOKENS: &[&str] = &[
"bg",
"fg",
"cursor",
"selection-bg",
"ansi-black",
"ansi-red",
"ansi-green",
"ansi-yellow",
"ansi-blue",
"ansi-magenta",
"ansi-cyan",
"ansi-white",
"ansi-bright-black",
"ansi-bright-red",
"ansi-bright-green",
"ansi-bright-yellow",
"ansi-bright-blue",
"ansi-bright-magenta",
"ansi-bright-cyan",
"ansi-bright-white",
];
/// The default dark theme.
pub const DARK: Theme = Theme {
id: "lutra-dark",
@ -97,6 +126,26 @@ pub const DARK: Theme = Theme {
("syntax-tag", "#e08b70"),
("syntax-attribute", "#cdb87e"),
("syntax-operator", "#b8afa6"),
("terminal-bg", "#191817"),
("terminal-fg", "#e6e1da"),
("terminal-cursor", "#d39a5c"),
("terminal-selection-bg", "#513f2c"),
("terminal-ansi-black", "#2e2b28"),
("terminal-ansi-red", "#ef7b6c"),
("terminal-ansi-green", "#a9bd7e"),
("terminal-ansi-yellow", "#e6c46f"),
("terminal-ansi-blue", "#8fa8e0"),
("terminal-ansi-magenta", "#c4a0d6"),
("terminal-ansi-cyan", "#7fbac6"),
("terminal-ansi-white", "#d0c9c1"),
("terminal-ansi-bright-black", "#9a928a"),
("terminal-ansi-bright-red", "#f59a8d"),
("terminal-ansi-bright-green", "#c2d69a"),
("terminal-ansi-bright-yellow", "#f2d88e"),
("terminal-ansi-bright-blue", "#aebff0"),
("terminal-ansi-bright-magenta", "#dbbde8"),
("terminal-ansi-bright-cyan", "#a2d3dc"),
("terminal-ansi-bright-white", "#f5f1ec"),
],
};
@ -135,6 +184,26 @@ pub const LIGHT: Theme = Theme {
("syntax-tag", "#a5432a"),
("syntax-attribute", "#695d1a"),
("syntax-operator", "#5a5149"),
("terminal-bg", "#fbfaf8"),
("terminal-fg", "#2a2622"),
("terminal-cursor", "#965a22"),
("terminal-selection-bg", "#e5d7c9"),
("terminal-ansi-black", "#2a2622"),
("terminal-ansi-red", "#b23a29"),
("terminal-ansi-green", "#4e6a24"),
("terminal-ansi-yellow", "#7a5808"),
("terminal-ansi-blue", "#2f55a4"),
("terminal-ansi-magenta", "#73479a"),
("terminal-ansi-cyan", "#24697a"),
("terminal-ansi-white", "#ddd6cd"),
("terminal-ansi-bright-black", "#6b625a"),
("terminal-ansi-bright-red", "#8f2a1c"),
("terminal-ansi-bright-green", "#3b5418"),
("terminal-ansi-bright-yellow", "#5f4404"),
("terminal-ansi-bright-blue", "#233f7f"),
("terminal-ansi-bright-magenta", "#5a3480"),
("terminal-ansi-bright-cyan", "#1a5260"),
("terminal-ansi-bright-white", "#f4f1ec"),
],
};
@ -280,6 +349,20 @@ mod tests {
}
}
#[test]
fn themes_define_the_terminal_tokens() {
for theme in BUILTIN {
let tokens = token_map(theme);
for name in TERMINAL_TOKENS {
assert!(
tokens.contains_key(&format!("--lt-terminal-{name}")),
"{} lacks terminal-{name}",
theme.id
);
}
}
}
#[test]
fn resolves_settings() {
assert_eq!(resolve("lutra-light", Some(true)), LIGHT);