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

@ -0,0 +1,57 @@
//! The methods of the control channel: names and documentation.
//!
//! Every request is `{"id", "method", "params"}` and gets one response line
//! (see [`crate::protocol`]). After `events.subscribe` the connection also
//! receives event lines `{"event": {...}}` between responses; each line is
//! written whole, so lines never interleave.
/// `app.ping`: liveness check.
pub const APP_PING: &str = "app.ping";
/// `engine.execute`: runs an engine command.
pub const ENGINE_EXECUTE: &str = "engine.execute";
/// `engine.listCommands`: lists the engine's commands.
pub const ENGINE_LIST_COMMANDS: &str = "engine.listCommands";
/// `ui.screenshot`: writes a PNG of the main window.
pub const UI_SCREENSHOT: &str = "ui.screenshot";
/// `events.subscribe`: streams engine events on this connection.
pub const EVENTS_SUBSCRIBE: &str = "events.subscribe";
/// Documentation of one method.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MethodDoc {
/// Method name.
pub name: &'static str,
/// Params.
pub params: &'static str,
/// Result.
pub result: &'static str,
}
/// Every method, for help output and agents.
pub const METHODS: &[MethodDoc] = &[
MethodDoc {
name: APP_PING,
params: "none",
result: "{ pong: true, version }",
},
MethodDoc {
name: ENGINE_EXECUTE,
params: "{ command: string, params?: object }",
result: "the command's result; errors carry the engine's code (unknown_command, disabled, invalid_params, stale_version, unsaved_changes, failed, internal)",
},
MethodDoc {
name: ENGINE_LIST_COMMANDS,
params: "none",
result: "[{ id, label, menuPath, defaultShortcut, params, enabled }]",
},
MethodDoc {
name: UI_SCREENSHOT,
params: "{ path: string }",
result: "{ path }; error screenshot_failed if the window cannot be captured",
},
MethodDoc {
name: EVENTS_SUBSCRIBE,
params: "none",
result: "{ subscribed: true }; then {\"event\": {kind, ...}} lines for every engine event until the connection closes. A subscriber that falls more than 4096 events behind is dropped and gets an {\"event\": {\"kind\": \"subscriptionLost\"}} line if possible",
},
];