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:
danny 2026-10-13 20:24:06 +02:00
parent 1fc46daa8e
commit b10a2a72f9
31 changed files with 421 additions and 9 deletions

2
.cargo/config.toml Normal file
View file

@ -0,0 +1,2 @@
[alias]
xtask = "run --quiet --package xtask --"

4
.gitattributes vendored Normal file
View file

@ -0,0 +1,4 @@
* text=auto eol=lf
*.png binary
*.ico binary
*.icns binary

55
Cargo.lock generated Normal file
View file

@ -0,0 +1,55 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
[[package]]
name = "lutra-cli"
version = "0.0.0"
[[package]]
name = "lutra-control"
version = "0.0.0"
[[package]]
name = "lutra-engine"
version = "0.0.0"
[[package]]
name = "lutra-index"
version = "0.0.0"
[[package]]
name = "lutra-lsp"
version = "0.0.0"
[[package]]
name = "lutra-mcp"
version = "0.0.0"
[[package]]
name = "lutra-search"
version = "0.0.0"
[[package]]
name = "lutra-syntax"
version = "0.0.0"
[[package]]
name = "lutra-terminal"
version = "0.0.0"
[[package]]
name = "lutra-testkit"
version = "0.0.0"
[[package]]
name = "lutra-text"
version = "0.0.0"
[[package]]
name = "lutra-vfs"
version = "0.0.0"
[[package]]
name = "xtask"
version = "0.0.0"

27
Cargo.toml Normal file
View file

@ -0,0 +1,27 @@
[workspace]
resolver = "3"
members = ["crates/*", "apps/*", "xtask"]
default-members = ["crates/*", "apps/*"]
[workspace.package]
version = "0.0.0"
edition = "2024"
rust-version = "1.88"
license = "MIT OR Apache-2.0"
authors = ["Daniel Diekert and the Lutra contributors"]
publish = false
[workspace.dependencies]
lutra-text = { path = "crates/text" }
lutra-syntax = { path = "crates/syntax" }
lutra-vfs = { path = "crates/vfs" }
lutra-index = { path = "crates/index" }
lutra-search = { path = "crates/search" }
lutra-lsp = { path = "crates/lsp" }
lutra-terminal = { path = "crates/terminal" }
lutra-engine = { path = "crates/engine" }
lutra-control = { path = "crates/control" }
lutra-mcp = { path = "crates/mcp" }
lutra-testkit = { path = "crates/testkit" }
[workspace.lints.rust]

17
apps/lutra-cli/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-cli"
description = "The lutra command-line tool"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 5
[dependencies]
[lints]
workspace = true

View file

@ -0,0 +1,10 @@
//! The `lutra` command-line tool (layer L5).
//!
//! Will open projects and files in a running Lutra, wait for tabs to close,
//! open the diff viewer and serve MCP. Until milestone M3 it only reports its
//! version.
/// Prints the version and exits.
fn main() {
println!("lutra {}", env!("CARGO_PKG_VERSION"));
}

17
crates/control/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-control"
description = "JSON-lines control channel"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 5
[dependencies]
[lints]
workspace = true

View file

@ -0,0 +1,4 @@
//! Control channel of Lutra (layer L5).
//!
//! Serves JSON lines on a local TCP port so that scripts and agents can run
//! engine commands and inspect the user interface.

17
crates/engine/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-engine"
description = "Command registry, workspace state, guard and recovery journal"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 4
[dependencies]
[lints]
workspace = true

4
crates/engine/src/lib.rs Normal file
View file

@ -0,0 +1,4 @@
//! Engine of Lutra (layer L4).
//!
//! Owns the command registry, the workspace state, the panic guard around every
//! entry point and the crash-recovery journal.

17
crates/index/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-index"
description = "Symbol index and usages"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 2
[dependencies]
[lints]
workspace = true

4
crates/index/src/lib.rs Normal file
View file

@ -0,0 +1,4 @@
//! Symbol index for Lutra (layer L2).
//!
//! Stores declarations and usages for go-to and find-usages, starting with
//! symbols extracted from tree-sitter trees.

17
crates/lsp/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-lsp"
description = "Language server client (Phpactor first), later a DAP client"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 3
[dependencies]
[lints]
workspace = true

4
crates/lsp/src/lib.rs Normal file
View file

@ -0,0 +1,4 @@
//! Language server client for Lutra (layer L3).
//!
//! Speaks the Language Server Protocol to external servers (Phpactor first)
//! and, later, the Debug Adapter Protocol. Server messages are untrusted input.

17
crates/mcp/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-mcp"
description = "MCP server over stdio"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 5
[dependencies]
[lints]
workspace = true

3
crates/mcp/src/lib.rs Normal file
View file

@ -0,0 +1,3 @@
//! MCP server of Lutra (layer L5).
//!
//! Exposes the engine commands as Model Context Protocol tools over stdio.

17
crates/search/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-search"
description = "Find in files"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 2
[dependencies]
[lints]
workspace = true

4
crates/search/src/lib.rs Normal file
View file

@ -0,0 +1,4 @@
//! Find in files for Lutra (layer L2).
//!
//! Streams matches from the project files off the UI thread, honouring the
//! ignore rules of the project model.

17
crates/syntax/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-syntax"
description = "tree-sitter parsing, outlines and highlight tokens"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 1
[dependencies]
[lints]
workspace = true

4
crates/syntax/src/lib.rs Normal file
View file

@ -0,0 +1,4 @@
//! Syntax layer for Lutra (layer L1).
//!
//! Parses source files with tree-sitter (PHP first) and derives outlines,
//! folding ranges and highlight tokens from the syntax tree.

View file

@ -0,0 +1,17 @@
[package]
name = "lutra-terminal"
description = "Pseudo-terminal sessions for the integrated terminal"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 3
[dependencies]
[lints]
workspace = true

View file

@ -0,0 +1,4 @@
//! Integrated terminal sessions for Lutra (layer L3).
//!
//! Spawns shells in pseudo-terminals and streams their output to the frontend,
//! where xterm.js renders it.

17
crates/testkit/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-testkit"
description = "Test helpers and fixtures, used by tests only"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = "tool"
[dependencies]
[lints]
workspace = true

View file

@ -0,0 +1,3 @@
//! Test helpers and fixtures for Lutra crates.
//!
//! Used only as a dev-dependency; never part of a shipped binary.

17
crates/text/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-text"
description = "Rope text buffer, positions, UTF-8/UTF-16 conversion and edits"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 0
[dependencies]
[lints]
workspace = true

5
crates/text/src/lib.rs Normal file
View file

@ -0,0 +1,5 @@
//! Text model for Lutra (layer L0).
//!
//! Holds the rope buffer, line and column positions, UTF-8/UTF-16 offset
//! conversion and edit application. Every other crate converts text offsets
//! through this crate instead of slicing strings by hand.

17
crates/vfs/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "lutra-vfs"
description = "Project model, file watching, ignore rules and encodings"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 2
[dependencies]
[lints]
workspace = true

4
crates/vfs/src/lib.rs Normal file
View file

@ -0,0 +1,4 @@
//! Virtual file system for Lutra (layer L2).
//!
//! Models an open project: its roots, ignore rules, file watching and text
//! encodings. File contents read here are untrusted input.

View file

@ -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 |

17
xtask/Cargo.toml Normal file
View file

@ -0,0 +1,17 @@
[package]
name = "xtask"
description = "Project automation: ci, layers, assets, cleanroom, dev, fixtures"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = "tool"
[dependencies]
[lints]
workspace = true

6
xtask/src/main.rs Normal file
View file

@ -0,0 +1,6 @@
//! Project automation for Lutra, run as `cargo xtask <command>`.
/// Entry point; the subcommands arrive with milestone M0.3.
fn main() {
println!("xtask");
}