M0.1: Cargo workspace with layered crates
Edition 2024 workspace with the crates from docs/architecture.md, each declaring its layer in package.metadata.lutra. Records the M0 architecture decisions (highlighting, Git library, terminal, text buffer). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
1fc46daa8e
commit
b10a2a72f9
31 changed files with 421 additions and 9 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Architecture
|
||||
|
||||
> **Status:** draft, to be completed in M0 · **Last updated:** 2026-10-13
|
||||
> **Status:** M0 decisions recorded · **Last updated:** 2026-10-13
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -10,35 +10,79 @@ ui/ (L6) Vue 3 + TypeScript + Vite frontend, Pinia, CodeMirror
|
|||
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
|
||||
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
|
||||
xtask (—) ci, layers, assets, cleanroom, dev, fixtures, lints-selftest, ui-licences
|
||||
```
|
||||
|
||||
A crate may depend only on crates of a lower layer. `cargo xtask layers` checks it. Nothing below L6 depends on Tauri or the frontend.
|
||||
Each crate declares its layer in its manifest:
|
||||
|
||||
```toml
|
||||
[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 }`.
|
||||
- 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()` (`unknown_command`, `disabled`, `invalid_params`, `failed`, `internal`) used by the control channel and the frontend.
|
||||
- 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 (M0): `app.ping`, `engine.execute {command, params}`, `engine.listCommands`, `ui.screenshot {path}`.
|
||||
- `lutra_control` defines a `Backend` trait; the desktop app implements it (engine access, effects, screenshots), tests implement it with a bare engine. One thread accepts connections and each connection gets its own thread; no async runtime is needed in the crate.
|
||||
- Screenshots: the desktop captures its own main window with `xcap` and writes a PNG.
|
||||
|
||||
## Frontend ↔ engine
|
||||
|
||||
The frontend calls `run(id, params)` over Tauri IPC and subscribes to state events (open buffers, diagnostics, tree changes). Buffer contents live in the engine; CodeMirror sends edits as transactions and receives authoritative changes back. Theme tokens are defined in Rust and exported as CSS variables.
|
||||
The frontend calls `run(id, params)` over Tauri IPC (`engine_execute`, `engine_list_commands`) and subscribes to state events (open buffers, diagnostics, tree changes). Buffer contents live in the engine; CodeMirror sends edits as transactions and receives authoritative changes back.
|
||||
|
||||
## Open questions for M0
|
||||
Theme tokens are defined in Rust (`lutra_engine::theme`) and rendered as CSS custom properties (`--lt-*`). The desktop injects them 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-…)`.
|
||||
|
||||
- Highlighting: tree-sitter tokens from the core vs. a Lezer grammar in CodeMirror for instant highlighting (tree-sitter stays the structural source either way).
|
||||
- Git library: `gix` (preferred, MIT/Apache) vs. alternatives.
|
||||
- Terminal: `portable-pty` in the core, xterm.js in the frontend.
|
||||
## 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 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-13 | major | M0: layers metadata, command and guard design, control protocol, open questions decided |
|
||||
| 2026-10-13 | major | Initial draft |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue