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

@ -0,0 +1,212 @@
//! `terminal.*` with a real shell (`cmd.exe` on Windows, `/bin/sh`
//! elsewhere): output and exits arrive through the pump; project close and
//! `app.quit` close terminals.
//!
//! ConPTY asks for the cursor position (`ESC[6n`) when it starts and waits
//! for the answer, which xterm.js gives in the app and [`Pumped`] gives here.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::indexing_slicing
)]
use std::time::{Duration, Instant};
use lutra_engine::cmd::terminal::{MAX_OUTPUT_PER_TERMINAL, TerminalEvent};
use lutra_engine::{Engine, Event};
use serde_json::{Value, json};
use tempfile::TempDir;
fn shell() -> &'static str {
if cfg!(windows) { "cmd.exe" } else { "sh" }
}
fn open_project() -> (TempDir, Engine) {
let dir = tempfile::tempdir().unwrap();
let mut engine = Engine::new().unwrap();
engine
.execute("project.open", json!({"path": dir.path()}))
.unwrap();
(dir, engine)
}
fn create(engine: &mut Engine) -> u64 {
let out = engine
.execute(
"terminal.create",
json!({"shell": shell(), "cols": 100, "rows": 30}),
)
.unwrap();
out.value["terminalId"].as_u64().unwrap()
}
/// What the pump reported for one terminal.
#[derive(Default)]
struct Pumped {
output: String,
exit: Option<Option<i64>>,
largest: usize,
answered: usize,
}
/// Pumps until `done` holds or the terminal exited, for at most 30 s.
fn pump_until(engine: &mut Engine, id: u64, seen: &mut Pumped, done: impl Fn(&str) -> bool) {
let deadline = Instant::now() + Duration::from_secs(30);
while Instant::now() < deadline {
for event in engine.pump_vfs().unwrap() {
match event {
Event::Terminal(TerminalEvent::TerminalOutput { terminal_id, data })
if terminal_id == id =>
{
assert!(!data.is_empty());
seen.largest = seen.largest.max(data.len());
seen.output.push_str(&data);
}
Event::Terminal(TerminalEvent::TerminalExited { terminal_id, code })
if terminal_id == id =>
{
seen.exit = Some(code);
}
_ => {}
}
}
while seen.answered < seen.output.matches("\x1b[6n").count() {
input(engine, id, "\x1b[1;1R").unwrap();
seen.answered += 1;
}
if seen.exit.is_some() || done(&seen.output) {
return;
}
std::thread::sleep(Duration::from_millis(10));
}
}
fn input(engine: &mut Engine, id: u64, data: &str) -> Result<Value, lutra_engine::EngineError> {
engine
.execute("terminal.input", json!({"terminalId": id, "data": data}))
.map(|o| o.value)
}
#[test]
fn create_output_input_exit() {
let (_dir, mut engine) = open_project();
let id = create(&mut engine);
assert_eq!(engine.state().terminals.len(), 1);
let mut seen = Pumped::default();
input(&mut engine, id, "echo lutra-term\r").unwrap();
pump_until(&mut engine, id, &mut seen, |out| {
out.matches("lutra-term").count() >= 2
});
assert!(seen.output.contains("lutra-term"), "{:?}", seen.output);
engine
.execute(
"terminal.resize",
json!({"terminalId": id, "cols": 60, "rows": 20}),
)
.unwrap();
input(&mut engine, id, "exit 7\r").unwrap();
pump_until(&mut engine, id, &mut seen, |_| false);
assert_eq!(seen.exit, Some(Some(7)));
assert!(seen.largest <= MAX_OUTPUT_PER_TERMINAL);
assert!(engine.state().terminals.is_empty());
let err = input(&mut engine, id, "x").unwrap_err();
assert_eq!(err.code(), "invalid_params");
}
#[test]
fn bad_params_fail() {
let (_dir, mut engine) = open_project();
for params in [
json!({"cols": 0, "rows": 10}),
json!({"cols": 80, "rows": 1001}),
json!({"cols": 80}),
json!({"cols": 80, "rows": 24, "cwd": "no-such-dir"}),
json!({"cols": 80, "rows": 24, "extra": 1}),
] {
let err = engine
.execute("terminal.create", params.clone())
.unwrap_err();
assert_eq!(err.code(), "invalid_params", "{params}");
}
let err = engine
.execute(
"terminal.create",
json!({"cols": 80, "rows": 24, "shell": "lutra-no-such-shell-x"}),
)
.unwrap_err();
assert_eq!(err.code(), "failed");
let id = create(&mut engine);
let big = "x".repeat(lutra_engine::cmd::terminal::MAX_INPUT_BYTES + 1);
assert_eq!(
input(&mut engine, id, &big).unwrap_err().code(),
"invalid_params"
);
let err = engine
.execute(
"terminal.resize",
json!({"terminalId": id, "cols": 0, "rows": 5}),
)
.unwrap_err();
assert_eq!(err.code(), "invalid_params");
let err = engine
.execute(
"terminal.resize",
json!({"terminalId": 99, "cols": 10, "rows": 5}),
)
.unwrap_err();
assert_eq!(err.code(), "invalid_params");
}
#[test]
fn close_project_close_and_quit_end_terminals() {
let (_dir, mut engine) = open_project();
let a = create(&mut engine);
let out = engine
.execute("terminal.close", json!({"terminalId": a}))
.unwrap();
assert_eq!(out.value["closed"], true);
assert!(
out.events
.contains(&Event::Terminal(TerminalEvent::TerminalExited {
terminal_id: a,
code: None,
}))
);
let out = engine
.execute("terminal.close", json!({"terminalId": a}))
.unwrap();
assert_eq!(out.value["closed"], false);
let b = create(&mut engine);
let out = engine.execute("project.close", json!({})).unwrap();
assert!(
out.events
.contains(&Event::Terminal(TerminalEvent::TerminalExited {
terminal_id: b,
code: None,
}))
);
assert!(engine.state().terminals.is_empty());
let err = engine
.execute("terminal.create", json!({"cols": 80, "rows": 24}))
.unwrap_err();
assert_eq!(err.code(), "disabled");
let (_dir2, mut engine) = open_project();
let c = create(&mut engine);
let d = create(&mut engine);
assert!(d > c);
let out = engine.execute("app.quit", json!({})).unwrap();
for id in [c, d] {
assert!(
out.events
.contains(&Event::Terminal(TerminalEvent::TerminalExited {
terminal_id: id,
code: None,
}))
);
}
assert!(engine.state().terminals.is_empty());
}