M1.3: engine workspace, file and buffer commands, event stream

State holds the open project (VFS project, watcher, watched directories)
and versioned buffers. New commands: project.open/close/children,
file.open/save/saveAll, buffer.get/edit/close. buffer.edit takes UTF-16
change sets based on a version and fails with the new stale_version code;
closing dirty buffers or projects without force fails with
unsaved_changes. Commands queue events (projectOpened, treeChanged,
bufferChanged, dirtyChanged, fileChangedOnDisk, ...) that the engine
returns in Outcome.events; Engine::pump_vfs maps changes on disk to
events and reloads clean buffers. project.children watches listed
directories, capped at 256 native / 32 polling, least recently listed
dropped first.

Control channel: events.subscribe streams {"event": ...} lines, with
bounded per-subscriber queues (lutra_control::Subscribers) and method docs
in methods.rs. testkit's EngineBackend and the desktop Host implement the
new Backend::subscribe. Verified with 14 engine integration tests, a TCP
events test and the running app over the control channel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-14 20:24:44 +02:00
parent a63ab4ac45
commit f1976c7d67
30 changed files with 2235 additions and 46 deletions

View file

@ -43,9 +43,9 @@ Every user-visible action is a command: `id`, `label`, `menu_path`, `default_sho
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 }`.
- `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()` (`unknown_command`, `disabled`, `invalid_params`, `failed`, `internal`) used by the control channel and the frontend.
- `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
@ -58,16 +58,32 @@ As built in M0:
- 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.
- 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 (open buffers, diagnostics, tree changes). Buffer contents live in the engine; CodeMirror sends edits as transactions and receives authoritative changes back.
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 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-…)`.
### 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}`, `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`. Events say what changed; clients fetch data with `project.children` and `buffer.get`.
Changes on disk reach the engine through `Engine::pump_vfs()`, which hosts call regularly (the desktop's pump thread arrives with M1.4; 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.
## Decisions (M0)
| Question | Decision | Why |
@ -85,6 +101,7 @@ Theme tokens are defined in Rust (`lutra_engine::theme`) and rendered as CSS cus
| Date | Change | Summary |
|---|---|---|
| 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 |

View file

@ -1,14 +1,14 @@
# Gaps
> **Status:** M0 closed G1; G2 under way (text buffer) · **Last updated:** 2026-10-14
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers) · **Last updated:** 2026-10-14
Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated.
| # | Gap | Milestone | Estimate (one agent) |
|---|---|---|---|
| G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) |
| G2 | Editor core: buffers, undo, multi-caret, save, recovery journal | M1 | ~30 h |
| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), project tree (UI exists against a mocked engine, M1.5; wiring after M1.3/M1.4), tabs; command palette, settings, theme switching | M1 | ~27 h |
| G2 | Editor core: ~~engine buffers, save~~ (M1.3), editor UI, undo, multi-caret, recovery journal | M1 | ~25 h |
| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), project tree (UI exists against a mocked engine, M1.5; engine side with `project.children` and tree events landed in M1.3; wiring in M1.4), tabs; command palette, settings, theme switching | M1 | ~27 h |
| G4 | Syntax and structure: tree-sitter PHP, Lezer highlighting, file structure | M2 | ~15 h |
| G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h |
| G6 | Language server: completion, diagnostics, definition, hover, rename via Phpactor | M3 | ~45 h |
@ -23,7 +23,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t
| G15 | Database tools, HTTP client, Docker and remote | later | ~430 h |
| G16 | Plug-ins and ecosystem | later | ~120 h |
G2 progress: the engine text buffer landed (M1.1, `crates/text`: rope, UTF-16 and char positions, atomic edit batches, line ending policy). Engine buffers, undo, multi-caret, save and the recovery journal are still open; the estimate stays ~30 h.
G2 progress: the engine text buffer landed (M1.1, `crates/text`: rope, UTF-16 and char positions, atomic edit batches, line ending policy). M1.3 added engine buffers with versions, the edit protocol, save and save all, and reloading on external changes. Still open: the editor UI, undo, multi-caret and the recovery journal; estimate lowered to ~25 h.
Known smaller items from M0:
@ -35,6 +35,7 @@ Known smaller items from M0:
| Date | Change | Summary |
|---|---|---|
| 2026-10-14 | minor | G2 shrunk, G3 note: engine workspace (M1.3) |
| 2026-10-14 | minor | G3 note: project tree UI (M1.5) |
| 2026-10-14 | minor | G2 note: text buffer landed (M1.1) |
| 2026-10-14 | minor | G3: native file watching (M1.2b); notify item resolved (CC0-1.0 approved for notify) |

View file

@ -1,13 +1,13 @@
# Milestones
> **Status:** M0 done, current focus M1 · **Last updated:** 2026-10-14
> **Status:** M0 done, M1 in progress · **Last updated:** 2026-10-14
Hours are agent wall-clock hours for one agent; M0 is measured, the rest estimated.
| Milestone | Goal | State | Hours |
|---|---|---|---:|
| M0 | Foundation: workspace, lints, quality gate, command registry, control channel, empty window | done 2026-10-14 (CI workflow written, not yet run: no remote) | ~2 (measured) |
| M1 | Editor and project: open folder, tree, tabs, editor, save, recovery, palette, settings, themes | not started | ~60 |
| M1 | Editor and project: open folder, tree, tabs, editor, save, recovery, palette, settings, themes | in progress (M1.1 text, M1.2 VFS, M1.5 tree UI, M1.3 engine workspace) | ~60 |
| M2 | Syntax and search: highlighting, structure, find in files, go to file/class/symbol | not started | ~50 |
| M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI and MCP — **MVP** | not started | ~80 |
| M4 | Git: status, diff, commit, branches, log, blame, conflicts | not started | ~150 |
@ -31,5 +31,6 @@ By the estimates above the alpha gate needs M1–M4 plus cross-platform verifica
| Date | Change | Summary |
|---|---|---|
| 2026-10-14 | minor | M1 in progress |
| 2026-10-14 | minor | M0 done; hours per milestone |
| 2026-10-13 | major | Initial milestones |

View file

@ -1,6 +1,6 @@
# Target-app parity
> **Status:** M1 in progress (text buffer landed), no PHP feature ships · **Last updated:** 2026-10-14 · **Target:** PhpStorm 2026.x
> **Status:** M1 in progress (text buffer, VFS, tree UI, engine workspace landed), no PHP feature ships · **Last updated:** 2026-10-14 · **Target:** PhpStorm 2026.x
## How this is measured
@ -12,8 +12,8 @@ Hours are the estimated agent wall-clock hours for one agent to reach behaviour
| Area | Weight | Score | Missing | Hours (one agent) | Evidence |
|---|---:|---:|---|---:|---|
| Editor core | 12 | 0% | everything user-visible; only the engine text buffer exists | ~120 (est.) | `crates/text`: rope buffer, positions, edits (M1.1, unit tests + proptests) |
| Project view, VFS | 6 | 0% | everything reachable in the app: tree not wired to the engine yet, file commands | ~37 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), native file watching via `notify` with a polling fallback, capped UTF-8 reads, atomic writes; 34 tests on temp dirs, watcher tests run on both backends (`crates/vfs/tests`). M1.5: project tree UI (lazy listing, keyboard navigation, dimmed ignored entries, event refresh) in `ui/src/components/project/`, Vitest against a mocked engine |
| Editor core | 12 | 0% | everything user-visible: no editor in the UI yet; engine buffers, file commands and events exist | ~120 (est.) | `crates/text`: rope buffer, positions, edits (M1.1, unit tests + proptests). M1.3: engine buffers with versions and dirty state, `file.open`, `buffer.get`, `buffer.edit` (UTF-16 change sets, `stale_version`), `file.save`, `file.saveAll`, `buffer.close` with unsaved-changes guard, line ending and BOM kept on save, clean buffers reload on external change; 14 integration tests on temp dirs (`crates/engine/tests/workspace.rs`) |
| Project view, VFS | 6 | 0% | everything reachable in the app: the tree UI is not wired to the engine yet (M1.4) | ~37 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), native file watching via `notify` with a polling fallback, capped UTF-8 reads, atomic writes; 34 tests on temp dirs, watcher tests run on both backends (`crates/vfs/tests`). M1.5: project tree UI (lazy listing, keyboard navigation, dimmed ignored entries, event refresh) in `ui/src/components/project/`, Vitest against a mocked engine. M1.3: `project.open`, `project.close`, `project.children` (watches listed directories, capped at 256 native / 32 polling, least recently listed dropped), `treeChanged` events from disk, `events.subscribe` on the control channel with a TCP test (`crates/control/tests/events.rs`) |
| Navigation | 10 | 0% | everything | ~120 (est.) | — |
| Search and replace | 6 | 0% | everything | ~80 (est.) | — |
| Code completion | 10 | 0% | everything | ~250 (est.) | — |
@ -62,6 +62,7 @@ Nothing user-visible yet, so every score stays 0%.
| Date | Change | Summary |
|---|---|---|
| 2026-10-14 | minor | Project view evidence: project tree UI (M1.5), score unchanged |
| 2026-10-14 | minor | M1.3 engine workspace evidence (Editor core, Project view; scores unchanged) |
| 2026-10-14 | minor | M1.1 text buffer evidence (Editor core, score unchanged) |
| 2026-10-14 | minor | Project view evidence: native file watching (M1.2b), score unchanged |
| 2026-10-14 | minor | Project view evidence: `lutra-vfs` (M1.2), score unchanged |