Lutra/docs/architecture.md
danny 2f8fef876b
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run
PM: merge M1.12 notifications
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	docs/architecture.md
#	docs/gaps.md
#	docs/roadmap.md
#	docs/target-app-parity.md
#	docs/ui-parity.md
2026-10-16 16:22:22 +02:00

31 KiB
Raw Blame History

Architecture

Status: M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal and notifications documented · Last updated: 2026-10-16

Overview

apps/lutra-desktop  (L6)  Tauri 2 shell: windows, menus, IPC bridge to the engine
ui/                 (L6)  Vue 3 + TypeScript + Vite frontend, Pinia, CodeMirror 6
apps/lutra-cli      (L5)  the `lutra` command: open, diff, --wait, mcp, perf, bench
crates/control      (L5)  JSON-lines control channel (--control PORT)
crates/mcp          (L5)  MCP server over stdio
crates/engine       (L4)  command registry, workspace state, guard, recovery journal, theme tokens
crates/lsp          (L3)  LSP client (Phpactor first), later DAP client
crates/terminal     (L3)  pseudo-terminal sessions (portable-pty)
crates/index        (L2)  symbol index, usages, later type inference
crates/vfs          (L2)  project model, file watching, ignore rules, encodings
crates/search       (L2)  find in files (ignore + grep-searcher crates)
crates/syntax       (L1)  tree-sitter parsing (PHP first), outlines, highlight tokens
crates/text         (L0)  rope buffer, positions, UTF-8/UTF-16 conversion, edits
crates/testkit      (—)   test helpers and fixtures, tests only
xtask               (—)   ci, layers, assets, cleanroom, dev, fixtures, lints-selftest, ui-licences

Each crate declares its layer in its manifest:

[package.metadata.lutra]
layer = 4        # or "tool" for testkit and xtask

cargo xtask layers reads cargo metadata and fails when

  • a crate has no layer;
  • a normal or build dependency points to a workspace crate of the same or a higher layer;
  • a crate with a numeric layer has a tool crate (testkit, xtask) as a normal or build dependency (dev-dependencies are fine);
  • a crate below L6 reaches a tauri or tauri-* package through its normal dependencies, directly or transitively.

Commands

Every user-visible action is a command: id, label, menu_path, default_shortcut, params (documented schema), enabled(&State) -> bool, run(&mut State, Params) -> Result<Output, EngineError>. Menus, the palette, keymaps, the CLI, the control channel and MCP all call the registry. Long-running commands report progress and can be cancelled.

As built in M0:

  • lutra_engine::Command is a trait with spec(), enabled() and run(). spec() returns a CommandSpec with the static metadata. Params and results are serde_json::Value; each command documents its params in CommandSpec::params.
  • Engine::execute(id, params) looks the command up, checks enabled, runs it inside the guard and returns an Outcome { value, effects, events }. Commands queue events with State::emit; the engine moves them into the outcome. Events queued by a command that then fails stay queued and arrive with the next outcome, Engine::pump_vfs or Engine::take_events.
  • Effects are requests the engine cannot fulfil below L6 (Effect::Quit so far). The host (desktop, tests) applies them after the command returns. Commands never call into Tauri.
  • EngineError has a stable string code() used by the control channel and the frontend: unknown_command, disabled (e.g. a file command without a project), invalid_params, stale_version (a buffer.edit based on an old version), unsaved_changes (closing a dirty buffer or project without force), failed, internal.
  • Shortcut notation: Mod is Ctrl on Windows and Linux and Cmd on macOS (Mod+Q). Default shortcuts are Lutra's own.

Guard

lutra_engine::guard::run wraps a closure in std::panic::catch_unwind and turns a panic into EngineError::Internal. Release builds keep panic = "unwind" for this reason; panic = "abort" is never set. The engine is held in a Mutex by the hosts; because the guard runs inside the lock, a panicking command never poisons it, and hosts still recover a poisoned lock with into_inner instead of unwrapping.

Control channel

--control PORT binds 127.0.0.1:PORT only. If binding fails, the desktop app prints the error and exits with status 1.

  • Transport: one JSON object per line, UTF-8, at most 16 MiB per line; longer lines get an error response and the connection is closed.
  • Request: {"id": <number|string>, "method": "<name>", "params": {...}}. Response: {"id": ..., "result": ...} or {"id": ..., "error": {"code": "...", "message": "..."}}. A line that is not valid JSON gets an error response with "id": null.
  • Methods: app.ping, engine.execute {command, params}, engine.listCommands, ui.screenshot {path}, events.subscribe. Names and docs live in crates/control/src/methods.rs.
  • events.subscribe answers {subscribed: true} and from then on writes {"event": {...}} lines for every engine event on that connection, between responses; a shared writer writes each line whole. Subscribing twice is a no-op. Each subscriber has a queue of 4096 events (lutra_control::EVENT_QUEUE); a subscriber that falls behind or disconnects is dropped by Subscribers::publish, and the connection gets a final {"event": {"kind": "subscriptionLost"}} line if it is still open.
  • lutra_control defines a Backend trait; the desktop app implements it (engine access, effects, screenshots, event subscribers), tests implement it with a bare engine (lutra_testkit::EngineBackend). Hosts publish each outcome's events through lutra_control::Subscribers. One thread accepts connections and each connection gets its own thread; no async runtime is needed in the crate.
  • Screenshots: xcap does not enumerate windows of its own process (querying their titles can deadlock), so the desktop focuses its main window, reads the client area's physical position and size from Tauri and captures that region of the monitor with xcap::Monitor::capture_region. Windows covering Lutra at that moment appear in the image. A webview-native capture (WebView2 CapturePreview, WKWebView snapshots) can replace it later.

Frontend ↔ engine

The frontend calls run(id, params) over Tauri IPC (engine_execute, engine_list_commands) and subscribes to state events. Buffer contents live in the engine; CodeMirror sends edits as transactions and receives authoritative changes back.

Theme tokens are defined in Rust (lutra_engine::theme) and rendered as CSS custom properties (--lt-*). The desktop injects the stored theme with the window's initialization script, so the first frame is already themed and the frontend needs no round trip. Components use only var(--lt-…); switching is described under Themes.

Workspace (M1.3)

  • State holds project: Option<Workspace> (the lutra_vfs::Project, its watcher and the watched directories) and buffers (id → OpenBuffer { buffer: lutra_text::Buffer, path, version, saved_version, bom }). A buffer is dirty when version != saved_version. Ids are never reused.
  • Commands: project.open {path, force?}, project.close {force?}, project.children {dir?}, file.open {path} (returns the existing buffer if the file is already open), buffer.get {id}, buffer.edit {id, baseVersion, edits}, file.save {id} (Mod+S), file.saveAll (Mod+Alt+S), buffer.close {id, force?}. Everything except project.open is disabled without a project. Paths are project-relative with /; absolute paths are accepted when they lie inside the project; .. escapes are rejected by the VFS.
  • Edit protocol: edits are {from, to, insert} in UTF-16 code units, all relative to the text at baseVersion (CodeMirror change-set semantics), non-overlapping, applied atomically. A baseVersion other than the current version fails with stale_version and changes nothing; the client refetches with buffer.get and reapplies its pending changes. Each successful batch increments the version by one. Limits: 100,000 edits and 64 MiB inserted per call.
  • Saving writes Buffer::save_text (the file's dominant line ending) atomically through the VFS and keeps a UTF-8 byte order mark.

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). 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.

Watched directories: the VFS watcher is non-recursive, so project.children watches each directory it lists. At most 256 directories besides the root are watched natively and 32 when polling (each polled directory is rescanned every 100 ms); beyond that the least recently listed directory is unwatched, and listing it again re-watches it. Expanding a deep vendor/ therefore costs at most 256 native watches; changes in directories that dropped out are not reported until they are listed again. node_modules, ignored and hidden directories are never watched. The parent directory of every open buffer is pinned (M1.13, workspace::sync_buffer_dirs, run by Engine::execute after every command): it is watched even if the tree never listed it, so reloads and fileChangedOnDisk arrive for files opened by path from never-expanded folders. Pinned directories count against the cap but are never evicted while a buffer in them is open (with more pinned directories than the cap, the watched set exceeds it); after the last buffer in a directory closes, it ages out like a listed one. A buffer inside an ignored or hidden directory is still not watched.

Desktop bridge (M1.4)

  • The desktop host publishes every event, from commands and from its pump thread, to control channel subscribers and to the window as the Tauri event engine://event with the engine Event as payload. Events are published while the engine lock is held, so their order is the engine's order.
  • ui/src/ipc.ts exposes onEngineEvent(handler) => unsubscribe with the typed union EngineEventPayload. Once the subscriptions started together (all of them while the page mounts) are registered, ipc.ts calls the IPC command engine_ready once; the host then replays projectOpened and bufferOpened for the current state, followed by the notifications and watchFailed events published before (M1.12), to the window only. A project opened from the command line (lutra-desktop --control 7979 PATH) or before a page reload therefore still reaches the UI.
  • project.openDialog returns Effect::PickFolder; the host shows the native folder picker (tauri-plugin-dialog, from Rust, non-blocking) and runs project.open with the choice. At most one picker is open; cancelling does nothing. A folder that cannot be opened becomes a notification (M1.12): unsaved_changes a warning, anything else an error.
  • Capabilities: the main window may only listen to and unlisten from events (core:event:allow-listen, core:event:allow-unlisten). Engine commands are app commands and need no permission; the dialog plugin is used from Rust only, so the frontend gets no dialog permission.
  • Contract fix: the project UI from M1.5 was written against assumed shapes. ui/src/components/project/engineEvents.ts is now the adapter between the engine contract and the UI types: toProjectEvent translates {kind: "projectOpened", root, name} and friends into the store's events, and toTreeEntries translates project.children's {dir, entries: [{name, path, kind: file|directory|other, ignored, role}], truncated} into tree entries (kind: dir|file, role, excluded, special for other) plus truncated. Malformed entries are skipped; a result without entries becomes an ipc error on the directory.

Tabs and editor (M1.6)

  • ui/src/stores/editor.ts holds the tabs (buffer id, path, dirty, notice), the active tab and the close question. It adds a tab from the file.open result (opened from the tree) or, for a bufferOpened event it did not cause (control channel, replay after a reload), from buffer.get. bufferClosed, dirtyChanged, fileChangedOnDisk and project open/close update it; bufferFocused activates the tab and outranks adoptions still fetching, so the most recent open wins. The project tree ends a directory the engine listed only partly (truncated) with a note row (project.tree.truncated). ui/src/components/editor/engineEvents.ts checks event fields before the store sees them.
  • One BufferSync per tab (ui/src/components/editor/bufferSync.ts) owns the tab's CodeMirror EditorState; one EditorView shows the active tab's state, so undo history and selection survive tab switches. Every transaction goes through the sync. Local changes are sent with buffer.edit against the confirmed version, one call in flight, later keystrokes composed into the next call. On stale_version, or a bufferChanged with a newer version than ours, the sync fetches buffer.get, diffs it against the confirmed text, rebases unsent local changes over that diff (CodeMirror change-set mapping) and applies the remote part to the editor without adding it to undo history. A refused edit (other than stale) is reported and the editor returns to the engine text.
  • Line breaks: the engine keeps text as on disk and counts \r\n as two UTF-16 units; CodeMirror counts every break as one position. EngineText remembers which breaks are \r\n and converts positions when building edits; inserted breaks are sent with the buffer's line ending, so a CRLF file stays CRLF in memory. Text without \r\n (the common case) needs no table.
  • Save, save all and close run from the engine's default shortcuts (file.save Mod+S, file.saveAll Mod+Alt+S, buffer.close Mod+W), loaded with listCommands and matched by key code, with the active buffer as context. Saving and closing wait until the sync has no pending edits.
  • Closing a dirty tab asks Save / Don't Save / Cancel; buffer.close without force failing with unsaved_changes also leads to the question. Lutra saves only on request for now (no autosave).
  • Theme: the editor reads colours only from --lt-* tokens, including the editor tokens from M1.10 (selection, active line, cursor, gutter, match, editor font size); no fallbacks remain.

Message catalog (M1.11)

  • Every interface string comes from ui/src/i18n/en.json: flat dotted keys grouped by area (app.*, project.*, editor.*, common.*), kept sorted. Components and stores call t(key, params?) from ui/src/i18n; {name} placeholders are filled from params, a placeholder without a value stays as it is. A missing key returns the key itself and warns on the console in development builds; it never throws. hasMessage(key) tells whether a key exists, for keys that arrive at runtime (settings labelKey, notification messageKey).
  • No i18n dependency: the helper is ~20 lines, and plurals, a reactive locale and a second language are G14 work. vue-i18n (MIT) remains an option then.
  • Enforcement: ESLint vue/no-bare-strings-in-template is an error (bare text and title/aria-label/placeholder/alt attributes); the allowlist is the rule's punctuation plus ;, … and ×. The test ui/tests/i18n/catalog.test.ts scans ui/src for t("…") calls and fails on a key that is not in en.json and on a catalog key that no source uses. Keys used only at runtime need an exception there when they arrive.
  • Engine messages (EngineError.message, the app.about slogan, watchFailed) are English text from the engine and shown as they are; they move to message keys with G14. Frontend-made errors (unexpected result of …) use the catalog.

Engine construction (M1.9a)

  • EngineConfig { config_dir, data_dir } and Engine::with_config(config) -> Result<Engine, EngineError>. The desktop builds the Tauri app first, takes app_config_dir() and app_data_dir() from its path resolver, creates the engine, the host and the control channel, and creates the window in the setup hook. Engine::new() has no persistence (settings in memory only) and serves tests and the control test backend; lutra_testkit::engine_config(root) gives temp dirs for tests.
  • Construction never fails because of the settings file. Problems are queued as a warning notification event; the desktop takes the startup events and publishes them, and the window receives them on engine_ready (M1.12).

Settings (M1.9a)

  • <config_dir>/settings.json, a flat JSON object of dotted keys, written with lutra_vfs::write_atomic on every change. Unknown keys are kept; a stored value that fails validation counts as unset. Read with a 1 MiB cap.
  • A file that is not a JSON object (invalid JSON, not UTF-8, too large) is renamed to settings.json.bad-<YYYYMMDDTHHMMSSZ> (with -n if taken), the defaults are used and a notification {level: "warning", messageKey: "notification.settings.corrupt", message, params: {reason, backup}} is queued. If it cannot be moved, or the directory or file cannot be read, settings stay in memory for the session (notification.settings.corruptNotMoved, notification.settings.unavailable) so the file is never overwritten.
  • Keys: appearance.theme (lutra-dark|lutra-light|system, default system), editor.fontSize (int 8–48, default 14), ui.language (en). Defined in lutra_engine::settings::DEFS.
  • Commands: settings.list → [{key, type: enum|int, default, enumValues?, min?, max?, labelKey, descriptionKey, section}] (catalog keys settings.<key>.label / .description; section is an id shown with settings.section.<id>), settings.get {keys?} → {values}, settings.set {key, value} → {value}, settings.reset {key} → {value}. Unknown keys and bad values fail with invalid_params; a write failure fails with failed and changes nothing.
  • Events: settingsChanged {keys} when an effective value changes; notification {id, level: info|warning|error, messageKey?, message?, params?} (ids n1, n2…).

Notifications (M1.12)

  • Event: notification {id, level: info|warning|error, messageKey?, message?, params?}; ids n1, n2… from one sequence per engine. messageKey is a catalog key, message the English fallback. The engine emits them for settings (M1.9a) and journal (M1.7) problems; the host asks the engine for one with Engine::notify (same id sequence) for errors that have no caller to return to:
    • folder picker and command-line path: notification.project.unsavedChanges {path, what} (warning) for unsaved_changes, notification.project.openFailed {path, reason} (error) otherwise, notification.project.notLocal {reason} (error) for a picked folder that is not a local path;
    • pump: notification.vfs.pumpFailed {reason} (warning), once until a pump succeeds again.
  • Replay: the host keeps notifications and watchFailed published before the window called engine_ready (at most 50) and sends them after the state replay; afterwards nothing is kept. The store ignores an id it already shows, so a second replay does not duplicate.
  • watchFailed stays an engine event (control channel clients use it); the frontend maps it to a warning toast notification.watch.failed {reason}. workspace.rs is unchanged.
  • UI: ui/src/stores/notifications.ts (Pinia) turns events into toasts (catalog text with params if the key exists, else message, else the key; untrusted fields checked, unknown levels count as errors) and offers notify / notifyError(command, error) to frontend code. Failed commands that have no UI of their own raise an error toast notification.command.failed {command, message} (today theme.systemPreference and loading the editor keymap); errors shown in place (tree listings, editor and project errors, the restore dialog) stay in place. ui/src/components/notifications/NotificationStack.vue, mounted in App.vue, stacks the toasts at the bottom right, newest at the bottom: info as role="status", dismissed after 5 s; warnings and errors as role="alert", until closed. Each toast has a close button and closes with Escape while focused; at most 5 show, older ones collapse into a "+n more" button that expands the stack; at most 100 are kept. Colours are the editor notices' (--lt-notice-bg, error tint), with a level stripe (muted, accent, error).

Themes (M1.10)

  • lutra_engine::theme defines DARK (lutra-dark) and LIGHT (lutra-light) with the same token names, plus shared font tokens. Besides the base colours (bg, editor-bg, fg, fg-muted, border, accent, error, statusbar-*) both define editor-selection-bg, editor-active-line-bg, editor-cursor, editor-gutter-bg, editor-gutter-fg, editor-match-bg, tab-active-bg, tab-modified, notice-bg; font-size-editor is shared (14px). Values are opaque #rrggbb derived from the palette (selection, match and notice are the accent mixed into the background); the designer may change values, never names.
  • appearance.theme selects the theme: a theme id or system. theme::resolve(setting, system_dark) picks the theme; system follows the OS preference the frontend reports, and counts as dark until it has.
  • Commands: theme.list → [{id, label, dark}] (label is a catalog key, theme.lutraDark/theme.lutraLight); theme.systemPreference {dark} stores the OS preference and returns the resolved theme {id, dark, tokens}. Switching goes through settings.set appearance.theme (or settings.reset).
  • Event: themeChanged {id, dark, tokens: {"--lt-…": value}} (every token, shared ones included) whenever the resolved theme changes: after settingsChanged for appearance.theme, or after theme.systemPreference in system mode. A change that resolves to the same theme (lutra-dark → system on a dark OS) emits nothing.
  • First frame: the desktop reads appearance.theme before creating the window and passes theme::init_script(setting), which installs <style id="lt-theme">. For system the CSS is the dark theme plus the light one inside @media (prefers-color-scheme: light), so the first frame follows the OS without a round trip; the native window background is set from the resolved theme (Window::theme() for system).
  • Live switch: ui/src/theme.ts (startTheme, called by App.vue) reports matchMedia("(prefers-color-scheme: dark)") now and on every change, applies the result and every themeChanged: tokens go onto :root's inline style (which wins over the injected style element), color-scheme is set, and data-theme holds the id. No reload.
  • Accessibility: ui/tests/theme/contrast.test.ts checks every text/background pair the components draw with against WCAG AA (4.5:1 text, 3:1 cursor and modified dot) in both themes. It reads ui/tests/theme/themes.json, which the Rust test theme::tests::ui_snapshot_is_current keeps equal to the Rust definition (LUTRA_UPDATE_SNAPSHOTS=1 rewrites it). ui/tests/theme/theme.test.ts fails on a var(--lt-x) the themes lack and on a fallback for a token they define.
  • Not themed yet: the native title bar follows the OS, not the Lutra theme; spacing and size tokens (--lt-space-*, --lt-radius, --lt-row-height…) are still CSS fallbacks in components; editor.fontSize does not drive --lt-font-size-editor yet.

Recovery journal (M1.7)

  • Storage: <data_dir>/recovery/<project-id>/<entry-id>.json. The project id is the FNV-1a 64-bit hash of the canonical project root, the entry id the same hash of the project-relative path, each as 16 hex digits (FNV instead of std's hasher, whose output may change between Rust versions). One file per dirty buffer: {path, text, lineEnding, bom, savedAt}; text is the buffer text as held in memory (mixed line breaks included), lineEnding the ending it saves with, savedAt milliseconds since the Unix epoch. Engines without a config (Engine::new) keep no journal. Code: crates/engine/src/journal.rs, commands in cmd/recovery.rs.
  • Writing: buffer.edit only records the edit time. Engine::pump_vfs (the desktop's pump thread, every 100 ms) writes a buffer once it has been idle for 1 s, or 2 s after its first unwritten edit while typing continues, so an entry is on disk at most ~1.1 s after the last edit and never per keystroke. Writes use lutra_vfs::write_atomic. Engine::flush_journal() writes everything now (tests, hosts about to stop). Cost for a 1 MiB buffer (measured on Windows 11, journal_write_cost_for_a_one_megabyte_buffer): median 8.5 ms in a release build, 67 ms in a debug build, under the engine lock; a keystroke arriving meanwhile waits that long. Moving the write to a background thread is a follow-up if large files make it noticeable.
  • Removal: file.save/file.saveAll, buffer.close (also force), project.close/project.open with force and recovery.discard remove entries. Save and close remove only entries this session wrote or restored; entries left by a crashed session stay until restored or discarded. Editing such a file without restoring it overwrites its entry.
  • Commands and event: after project.open, recoveryAvailable {entries: [{path, savedAt, diskChanged}]} when the journal is not empty. recovery.list → {entries}; recovery.restore {paths?} → {restored: [{path, id}], failed: [{path, message}]} opens each file as a dirty buffer (version 1, saved version 0) with the journal text, line ending and BOM, or puts the text into a clean open buffer; a buffer with unsaved changes is newer than the journal and is left alone (failed); a file gone from disk is restored too and saving recreates it. recovery.discard {paths?} → {discarded}; a discarded entry of an open dirty buffer is written again on the next tick. diskChanged is true when the file's modification time is after savedAt or the file is gone.
  • Untrusted input: entries are read with a 512 MiB cap, at most 1,000 per project. An entry that is not valid JSON of that shape, whose path escapes the project or does not match its file name is renamed to <entry>.bad, skipped, and reported once as notification {level: warning, messageKey: "notification.recovery.corrupt", params: {file, reason}}. A failed write is reported once until a write succeeds (notification.recovery.writeFailed {path, reason}); an unreadable journal directory gives notification.recovery.unavailable {reason}. Neither stops editing or opening.
  • UI: ui/src/components/recovery/ (store recovery.ts, RecoveryDialog.vue, mounted in App.vue). The list comes from recoveryAvailable and, because that event is not replayed after a page reload, from recovery.list on projectOpened. Restore all, Restore selected (the rest stay listed) and Discard always pass explicit paths; Escape closes and keeps the journal for the next open.
  • Limits: two Lutra instances on the same project share one journal directory; diskChanged misses a disk change that happened before the last journal write.

Decisions (M0)

Question Decision Why
Highlighting A Lezer grammar (@lezer/php, MIT) in CodeMirror highlights instantly on the UI thread. tree-sitter in crates/syntax stays the structural source (outline, folding, index) and later adds semantic tokens on top. The keystroke-to-highlight budget (< 16 ms) leaves no room for an IPC round trip per keystroke; Lezer is incremental inside CodeMirror. tree-sitter gives the core one parser for every structural feature.
Git library gix (MIT OR Apache-2.0) for reading: status, log, diff, blame, refs. Writes the library doesn't cover well (push, pull, rebase, merge, hooks, signing) run the user's git executable. git2/libgit2 is not used. gix is pure Rust and permissively licensed; libgit2 is GPL-2.0 with a linking exception, outside the permitted licences. Shelling out for writes keeps the user's hooks, credential helpers and config working.
Terminal portable-pty (MIT) in the new L3 crate crates/terminal; xterm.js (MIT) renders in the frontend. Output is streamed as events, input goes through commands. ConPTY on Windows and Unix PTYs behind one API; xterm.js is the standard web terminal. A separate crate keeps PTY code out of the engine.
Text buffer ropey (MIT) in crates/text. Mature rope with line and UTF-16 helpers.
Clippy panic lints unwrap_used, expect_used, panic, unreachable, todo, unimplemented, indexing_slicing, string_slice are denied workspace-wide; clippy.toml allows them in #[test]/#[cfg(test)]; integration tests in tests/ and testkit allow them at crate level. missing_docs is denied too, to back the doc-comment code style. unsafe_code is denied; a crate that needs it allows it locally with a doc comment saying why. AGENTS.md › Never crash.
Desktop dev mode Plain cargo build/cargo run -p lutra-desktop is a Tauri dev build that loads the Vite dev server. cargo xtask dev [-- ARGS] starts both. A self-contained build embeds ui/dist through the bundled-ui feature. Keeps cargo build --workspace independent of the frontend build.
App identifier dev.lutra.desktop is a placeholder. The final reverse-DNS identifier depends on the project's domain and hosting, which are the owner's decision (execution plan §4); bundling stays off until then. Tauri requires an identifier to build.
App icon A placeholder (rounded otter-brown square with a pale stone) is generated by apps/lutra-desktop/build.rs into the gitignored apps/lutra-desktop/icons/. The real icon is the owner's to commission; ASSETS.md allows generated-in-code art.

Revision history

Date Change Summary
2026-10-16 minor M1.12: notifications (host emission, early-event replay, toast store and stack, deferred engine_ready)
2026-10-16 minor M1.13: open buffers pin their parent directory in the watcher, bufferFocused, truncated listing row
2026-10-16 minor M1.7: recovery journal (storage, debounce, removal, commands, recoveryAvailable, restore dialog)
2026-10-16 minor M1.10: themes (light theme, editor tokens, theme.list, theme.systemPreference, themeChanged, init script from the setting, live switch, contrast test)
2026-10-16 minor M1.9a: engine construction (EngineConfig, with_config) and settings (file, commands, settingsChanged, notification)
2026-10-15 minor M1.11: message catalog (t, lint rule, catalog test, engine messages stay English)
2026-10-15 minor M1.6: tabs and editor (buffer sync, CRLF offsets, shortcuts from command specs)
2026-10-15 minor M1.4: desktop bridge (engine://event, engine_ready replay, folder picker, capabilities), UI contract fix
2026-10-14 minor M1.3: workspace commands, edit protocol, events, events.subscribe, watched-directory limits
2026-10-14 minor Screenshot method, placeholder app identifier
2026-10-13 major M0: layers metadata, command and guard design, control protocol, open questions decided
2026-10-13 major Initial draft