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:
parent
5fa7f0c8b3
commit
a8daf269fb
45 changed files with 3935 additions and 49 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Architecture
|
||||
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty` · **Last updated:** 2026-10-20
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal · **Last updated:** 2026-10-20
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -113,7 +113,7 @@ Theme tokens are defined in Rust (`lutra_engine::theme`) and rendered as CSS cus
|
|||
|
||||
### Events
|
||||
|
||||
`lutra_engine::Event`, serialised as `{"kind": "<camelCase>", ...}`: `projectOpened {root, name}`, `projectClosed`, `treeChanged {dir}`, `bufferOpened {id, path}`, `bufferFocused {id}` (M1.13), `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`, `recoveryAvailable {entries}` (M1.7, see Recovery journal), `uiCommand {id, params}` (M1.8, see UI commands), `recoveryResolved {paths}` (M1.15, see Recovery journal), `searchResults {searchId, path, matches}` and `searchDone {searchId, files, matches, truncated, cancelled, elapsedMs}` (M2.3, see Search). Events say what changed; clients fetch data with `project.children` and `buffer.get`. `file.open` on a file whose buffer is already open returns that buffer and emits `bufferFocused {id}` instead of `bufferOpened` (M1.13): a separate event, so that `bufferOpened` keeps meaning "a new buffer exists" (the host's `engine_ready` replay and other clients rely on that) while every client, including the editor, still learns that the user asked to see that buffer and activates its tab.
|
||||
`lutra_engine::Event`, serialised as `{"kind": "<camelCase>", ...}`: `projectOpened {root, name}`, `projectClosed`, `treeChanged {dir}`, `bufferOpened {id, path}`, `bufferFocused {id}` (M1.13), `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`, `recoveryAvailable {entries}` (M1.7, see Recovery journal), `uiCommand {id, params}` (M1.8, see UI commands), `recoveryResolved {paths}` (M1.15, see Recovery journal), `searchResults {searchId, path, matches}` and `searchDone {searchId, files, matches, truncated, cancelled, elapsedMs}` (M2.3, see Search), `terminalOutput {terminalId, data}` and `terminalExited {terminalId, code}` (M3.6, see Terminal). Events say what changed; clients fetch data with `project.children` and `buffer.get`. `file.open` on a file whose buffer is already open returns that buffer and emits `bufferFocused {id}` instead of `bufferOpened` (M1.13): a separate event, so that `bufferOpened` keeps meaning "a new buffer exists" (the host's `engine_ready` replay and other clients rely on that) while every client, including the editor, still learns that the user asked to see that buffer and activates its tab.
|
||||
|
||||
Changes on disk reach the engine through `Engine::pump_vfs()`, which hosts call regularly (the desktop's pump thread every 100 ms; tests call it directly). It maps VFS events to `treeChanged` for the parent directories, reloads a clean buffer whose file changed (unless the file already matches, as after our own save) with `bufferChanged`, and reports `fileChangedOnDisk` for a dirty buffer, which keeps its text, or for a removed file. At most 10,000 VFS events are handled per pump.
|
||||
|
||||
|
|
@ -210,7 +210,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- **Listing:** `listCommands` returns one list in id order: engine commands and UI commands. `CommandInfo` has `ui: bool`; UI commands also carry `labelKey`, use it as `label` (the engine has no English for them) and are always `enabled` as far as the engine knows.
|
||||
- **Running from outside:** `Engine::execute` on a UI command id queues `uiCommand {id, params}` and returns `null` (params are passed on unchanged). The desktop publishes the event to the window and to control subscribers like any other. The frontend runs the command, so `engine.execute palette.open` over the control channel opens the palette. A `uiCommand` the frontend cannot run (no handler, or disabled) becomes a warning toast.
|
||||
- **Frontend:** `ui/src/commands/`:
|
||||
- `uiCommands.ts` lists the UI commands: `editor.reveal` (no shortcut, M2.2), `find.open` `Mod+Alt+F` (M2.4), `menu.open` `Alt+M` (M3.9), `palette.open` `Mod+Shift+P`, `settings.open` `Mod+,`, `view.toggleProjectTree` `Mod+1`. Since M3.9 the user-facing ones carry a `menuPath`.
|
||||
- `uiCommands.ts` lists the UI commands: `editor.reveal` (no shortcut, M2.2), `find.open` `Mod+Alt+F` (M2.4), `menu.open` `Alt+M` (M3.9), `palette.open` `Mod+Shift+P`, `settings.open` `Mod+,`, `terminal.open` `Mod+Shift+T` (M3.6), `view.toggleProjectTree` `Mod+1`. Since M3.9 the user-facing ones carry a `menuPath`.
|
||||
- `keymap.ts` parses Lutra notation and matches by key code (letters, digits and US punctuation by `code`, so Alt and Shift layout effects don't matter). It also formats shortcuts for display with catalog modifier names.
|
||||
- `rank.ts` ranks for the palette.
|
||||
- `store.ts` (Pinia `commands`) holds the merged list, the keymap, the handlers and the recent commands.
|
||||
|
|
@ -235,7 +235,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
|
||||
- **Where:** `MainLayout.vue` has a slim header bar (28 px, `--lt-bg`, a `header` slot) whose default content is `ui/src/components/menu/AppMenu.vue`: a button with the Lucide `menu` icon top left.
|
||||
- **Contents (`menu.ts`):** every command in the store's entries with a `menuPath` (engine and UI), grouped by the path's first segment. Groups in Lutra's order File, Edit, View, Go, Help (unknown groups before Help, empty ones hidden), group headings from the catalog (`menu.group.*`). Items follow a fixed id order, others sorted by label after them. A UI command shows its catalog label; an engine command shows the rest of its path (the engine has no catalog, and the path is written for menus), so `buffer.close` reads Close Tab. Deeper paths are flattened as `A › B`.
|
||||
- **Paths:** File (`project.openDialog`, `file.save`, `file.saveAll`, `buffer.close` → `File/Close Tab`, `project.close`, `app.quit`), View (`palette.open`, `view.toggleProjectTree`, `view.toggleStructure`, `find.open`, `settings.open`), Go (`goto.fileOpen`, `goto.classOpen`, `goto.symbolOpen`), Help (`app.about`). Edit stays empty until there are edit commands; the terminal toggle gets `View/Terminal` when M3.6 lands (its id is already in the order list).
|
||||
- **Paths:** File (`project.openDialog`, `file.save`, `file.saveAll`, `buffer.close` → `File/Close Tab`, `project.close`, `app.quit`), View (`palette.open`, `view.toggleProjectTree`, `view.toggleStructure`, `find.open`, `terminal.open` → `View/Terminal`, `settings.open`), Go (`goto.fileOpen`, `goto.classOpen`, `goto.symbolOpen`), Help (`app.about`). Edit stays empty until there are edit commands.
|
||||
- **Opening:** the button (a second click closes) or `menu.open` (`Alt+M`, Lutra's own; also as `uiCommand`). It refreshes the enabled states and focuses the first item.
|
||||
- **Keyboard:** WAI-ARIA menu with roving focus: arrows wrap, Home/End, Enter/Space runs, Escape or Tab closes, printable keys type ahead (500 ms buffer; one letter cycles through items with that initial). Disabled items are focusable, dimmed (`aria-disabled`) and do nothing.
|
||||
- **Modal rule:** `menu` is an exclusive `ModalId`; the menu is a launcher like the palette: `commands/store.ts` › `execute` closes it for every command but `menu.open`, so a shortcut, a palette command or an agent's `uiCommand` never leaves it open. A chosen command runs after the menu closed and returned the focus.
|
||||
|
|
@ -278,7 +278,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
|
||||
### Find tool window (M2.4)
|
||||
|
||||
- **Bottom panel:** `ui/src/components/layout/BottomPanel.vue`, under the editor and the left tool window, above the status bar: header with title, collapse/expand and close; a splitter on the top edge (pointer, or Up/Down with Shift for larger steps; 80–900 px, at most 75 % of the window). Height is view state of `MainLayout.vue`; later bottom tool windows (Problems, Terminal) reuse it. Only Find lives there today, so the panel shows while the Find store's `visible` is set; a tab strip comes with the second tool window.
|
||||
- **Bottom panel:** `ui/src/components/layout/BottomPanel.vue`, under the editor and the left tool window, above the status bar: header with title, collapse/expand and close; a splitter on the top edge (pointer, or Up/Down with Shift for larger steps; 80–900 px, at most 75 % of the window). Height is view state of `MainLayout.vue`; later bottom tool windows (Problems, Terminal) reuse it. Since M3.6 it also holds the Terminal tool window and shows tabs while both are visible (see Terminal).
|
||||
- **Store:** `ui/src/stores/find.ts` (Pinia `find`, started by the main layout) holds the query, the options (`regex`, `caseSensitive`, `wholeWord`, include/exclude as comma-separated globs), the current `searchId`, the files with their matches (a `shallowRef`, replaced per event, kept sorted by path because files arrive in no fixed order), the `searchDone` summary and an inline error.
|
||||
- **One search at a time:** a new search cancels the running one with `search.cancel` (the engine does not); results of other searches are ignored, and the answer of a search overtaken by a newer one is dropped and cancelled.
|
||||
- **Event race:** events and the `search.find` answer travel on different channels (Tauri event vs. invoke response), and the pump may publish results before the answer arrives. While `search.find` has not answered, search events are held (at most 5,000) and replayed for the returned id.
|
||||
|
|
@ -330,6 +330,18 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- Shutdown: `shutdown(self)` sends `shutdown` (waits up to 2 s), `exit`, kills after 1 s, fails what is pending with `Stopped` and reports `Stopped`; it blocks for up to about 3 s, so callers run it off the engine lock. Dropping the `Server` requests the same stop in the background.
|
||||
- URIs (`uri`): `path_to_uri` percent-encodes everything except unreserved characters, `/` and a drive colon (`file:///C:/a%20b.php`, UNC as `file://host/share`); `uri_to_path` accepts escapes in any case, an encoded drive colon and `localhost`, and upper-cases the drive letter; bad escapes, NUL and other schemes give `None`.
|
||||
- Tests: the fake server `src/bin/lutra-lsp-fake.rs` (a test fixture, started via `CARGO_BIN_EXE_lutra-lsp-fake`) covers initialize, server requests, log and stderr, typed requests and errors, queueing before ready, timeout and cancel with `$/cancelRequest`, incremental and full sync (the fake applies the changes and publishes the text as a diagnostic), malformed output, crash, restart and reopen, initialize errors, giving up with the backoff sequence, shutdown and spawn errors (13 tests, about 0.5 s). `real_phpactor` is ignored and runs with `LUTRA_PHPACTOR` (path to `phpactor.phar`, `LUTRA_PHP` for PHP); it was not run in M3.2 (no Phpactor on the dev machine yet; M3.1 downloads it).
|
||||
### Terminal (M3.6)
|
||||
|
||||
- **Library:** `crates/terminal` (L3) wraps `portable-pty` (MIT; ConPTY on Windows, a Unix pty elsewhere). `Session::spawn(SpawnOptions {shell, cwd, cols, rows, env})` starts the shell with `TERM=xterm-256color`, `COLORTERM=truecolor`, `TERM_PROGRAM=Lutra`. Each session has three threads, so no call blocks the caller: a reader (16 KiB reads, `Utf8Chunker` joins a character split across reads and turns invalid bytes into U+FFFD like `from_utf8_lossy`), a writer (input queue of at most 64 pieces of 64 KiB; a full queue fails with `InputFull` instead of blocking), and a waiter that records the exit code and then closes the pty, because ConPTY reports the end of output only once the pseudo console is closed. `default_shell()`: `pwsh.exe` from `PATH` (with `-NoLogo`), then `powershell.exe`, then `%COMSPEC%`/`cmd.exe` on Windows; `$SHELL` or `/bin/sh` on Unix.
|
||||
- **Buffer and drop policy:** each session buffers at most 1 MiB of decoded text (`OUTPUT_CAP`). When it is full the reader stops reading, so the shell blocks on its next write (backpressure): nothing is dropped while a session runs. Output still buffered when a session is closed or killed is dropped. `exit()` reports the code once the shell exited, its output was read to the end (or 500 ms passed, for a background process that keeps the pty open) and the buffer is empty, so the exit always follows the last output.
|
||||
- **Engine:** `cmd/terminal.rs`. `terminal.create {cwd?, shell?, cols, rows}` → `{terminalId}` (enabled with a project; cwd project-relative or absolute, default the root; 1–1000 columns and rows; at most 16 terminals), `terminal.input {terminalId, data}` (≤ 1 MiB), `terminal.resize {terminalId, cols, rows}`, `terminal.close {terminalId}` → `{closed}`. Events `terminalOutput {terminalId, data}` and `terminalExited {terminalId, code}` (`code: null` when Lutra closed the terminal) are the variants of `cmd::terminal::TerminalEvent`, appended to `Event` as one untagged variant so that `event.rs` takes a one-line append and each variant keeps its own `kind`. The pump emits one `terminalOutput` per terminal with at most 64 KiB, at most 256 KiB over all terminals, round-robin; with the desktop's 100 ms pump that caps the stream at about 2.5 MB/s and the shell waits beyond it. Under the engine lock only spawning, queueing input, resizing and killing happen.
|
||||
- **Lifecycle:** a terminal belongs to the project open when it was created. `cmd::terminal::sync_project` runs after every command and every pump and closes terminals whose project is gone (`project.close`, another `project.open`); `app.quit` closes all of them. Dropping a session kills its shell; when the process ends without that, the OS closes the pseudo console (ConPTY) or hangs up the pty (Unix).
|
||||
- **Cursor query:** ConPTY starts with `ESC[6n` and waits for the answer. xterm.js answers in the app; tests answer it themselves (`crates/terminal/tests/session.rs`, `crates/engine/tests/terminal.rs`, `crates/control/tests/terminal.rs`).
|
||||
- **Store:** `ui/src/stores/terminal.ts` (Pinia `terminal`): tabs, the active terminal, visibility and expansion of the Terminal tab, an output history per terminal (at most 512 Ki UTF-16 units, oldest event chunks dropped first) that a view replays when it mounts, output that arrives before `terminal.create` answered kept by id, input sent in order with one `terminal.input` in flight (keys typed meanwhile go together), sizes deduplicated. `projectClosed` drops everything.
|
||||
- **Views:** `ui/src/components/terminal/TerminalToolWindow.vue` has the sub-tab strip ("Local", "Local (2)"…, close buttons, a new-terminal button; Left/Right/Home/End/Delete on a tab) and one `TerminalView.vue` per terminal, kept mounted with `v-show`, so switching sub-tabs keeps xterm's screen; collapsing or hiding the panel unmounts them and the history restores them. `xterm.ts` is the only file that imports `@xterm/xterm` and `@xterm/addon-fit` (MIT), so tests mock it. The fit addon follows a `ResizeObserver` and reports the size with `terminal.resize`. Colours come from the `--lt-terminal-*` tokens (`terminal-bg`, `-fg`, `-cursor`, `-selection-bg` and 16 `-ansi-*` colours, Lutra's own palette), font and size from `--lt-font-mono` and `--lt-font-size-editor`; `themeChanged` re-themes running terminals. Every ANSI colour that shows as text reaches 4.5:1 on `terminal-bg` (contrast test), except the one meant to vanish (black in dark, white and bright white in light); xterm's `minimumContrastRatio` is 4.5, so text a program prints in such a colour (PSReadLine uses white) is darkened or lightened until it is readable. xterm's stylesheet paints the viewport black; the view overrides it with `--lt-terminal-bg`.
|
||||
- **Focus and shortcut rule** (`ui/src/components/terminal/keys.ts`, applied by the commands store's keydown listener): while a terminal has the focus, only shortcuts with Mod+Shift or Mod+Alt reach Lutra (on macOS every Cmd shortcut); plain Ctrl keys (`Ctrl+C`, `Ctrl+W`, `Ctrl+P`, `Ctrl+1`…) go to the shell. Copy: `Mod+Shift+C`, or `Ctrl+C` with a selection (`Cmd+C` on macOS) through `navigator.clipboard.writeText`. Paste: `Mod+Shift+V` or `Ctrl+V` (`Cmd+V`) are left to the browser, whose `paste` event xterm handles, so no clipboard-read permission is needed.
|
||||
- **Bottom panel tabs:** `BottomPanel.vue` takes `tabs` and `v-model:active`; with tabs the header shows a tab list instead of the title. `MainLayout.vue` shows Find and Terminal as tabs while both are visible; `find.open` and `terminal.open` make their tool window the active tab, the close button hides the active one, and expansion is kept per tool window.
|
||||
- **`terminal.open`** (UI command, `Mod+Shift+T`, Lutra's own; enabled with a project): shows the Terminal tab, creates a terminal if none is running (always with `{new: true}`) and focuses it.
|
||||
|
||||
### Toolchain (M3.1)
|
||||
|
||||
|
|
@ -376,6 +388,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
| 2026-10-20 | minor | M3.10: autosave (blur, tab switch, idle), `flushDirty`, `file.saveAll {skipConflicts}`, disk conflicts and own-write hashes in `Buffers` |
|
||||
| 2026-10-19 | minor | M3.8: MCP server (`lutra mcp`, dual era 2026-07-28 + legacy `initialize`), tools, resources, event buffer; `buffer.list` |
|
||||
| 2026-10-19 | minor | M3.9: app menu (header bar, `menu.open`, grouping by `menuPath`, launcher under the modal rule); menu paths for user commands |
|
||||
| 2026-10-18 | minor | M3.6: integrated terminal (`crates/terminal` sessions, backpressure, `terminal.*`, `terminalOutput`/`terminalExited` via the pump, lifecycle, xterm.js views, terminal tokens, focus rule, bottom panel tabs) |
|
||||
| 2026-10-18 | minor | M3.1: toolchain (PHP detection, pinned Phpactor download with SHA-256 check, network access note, D15), `toolchain.status`/`toolchain.downloadPhpactor`, `toolchainChanged`, bool and string settings |
|
||||
| 2026-10-18 | minor | M3.2: LSP client library (`crates/lsp`: framing, supervision and restart, initialize, requests with timeout and cancel, server requests, document sync, fake server tests) |
|
||||
| 2026-10-17 | minor | M3.7: `lutra` CLI, single instance, rendezvous file and token listener, `app.auth`/`app.focus`, CLI to L6 |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue