From f9357ee4b5fffbaba3d18f8d3171faae280829c1 Mon Sep 17 00:00:00 2001 From: danny Date: Fri, 16 Oct 2026 15:23:43 +0200 Subject: [PATCH] M1.9a: engine dirs and settings backend EngineConfig and Engine::with_config; the desktop resolves Tauri's app config and data dirs. Settings model (appearance.theme, editor.fontSize, ui.language) with typed validation, persistence in settings.json via write_atomic (1 MiB cap, unknown keys kept, corrupt file backed up with a warning notification), settings.list/get/set/reset, settingsChanged and notification events. Property test over random settings.json content, control-channel test for persistence and corrupt-file recovery. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + apps/lutra-desktop/src/host.rs | 12 +- apps/lutra-desktop/src/main.rs | 82 +++- crates/control/tests/events.rs | 59 +++ crates/engine/Cargo.toml | 1 + crates/engine/src/cmd/mod.rs | 5 + crates/engine/src/cmd/settings.rs | 159 +++++++ crates/engine/src/engine.rs | 49 ++- crates/engine/src/event.rs | 68 ++- crates/engine/src/lib.rs | 5 +- crates/engine/src/settings.rs | 669 ++++++++++++++++++++++++++++++ crates/engine/src/state.rs | 30 +- crates/engine/tests/settings.rs | 254 ++++++++++++ crates/testkit/src/lib.rs | 27 +- docs/architecture.md | 16 +- docs/gaps.md | 5 +- docs/target-app-parity.md | 5 +- 17 files changed, 1406 insertions(+), 41 deletions(-) create mode 100644 crates/engine/src/cmd/settings.rs create mode 100644 crates/engine/src/settings.rs create mode 100644 crates/engine/tests/settings.rs diff --git a/Cargo.lock b/Cargo.lock index a912c3c..a7bad2a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2523,6 +2523,7 @@ version = "0.0.0" dependencies = [ "lutra-text", "lutra-vfs", + "proptest", "serde", "serde_json", "tempfile", diff --git a/apps/lutra-desktop/src/host.rs b/apps/lutra-desktop/src/host.rs index f154c52..27ab186 100644 --- a/apps/lutra-desktop/src/host.rs +++ b/apps/lutra-desktop/src/host.rs @@ -49,19 +49,15 @@ pub struct Host { } impl Host { - /// A host with a fresh engine. - /// - /// # Errors - /// The engine's error if the built-in commands cannot be registered. - pub fn new() -> Result, EngineError> { - let engine = Engine::new()?; - Ok(Arc::new_cyclic(|me| Self { + /// A host around `engine`. + pub fn new(engine: Engine) -> Arc { + Arc::new_cyclic(|me| Self { engine: Mutex::new(engine), app: OnceLock::new(), subscribers: Subscribers::default(), me: me.clone(), picking: AtomicBool::new(false), - })) + }) } /// Records the app handle once Tauri has started. Later calls are diff --git a/apps/lutra-desktop/src/main.rs b/apps/lutra-desktop/src/main.rs index 728ca45..c11b33a 100644 --- a/apps/lutra-desktop/src/main.rs +++ b/apps/lutra-desktop/src/main.rs @@ -12,12 +12,12 @@ mod host; mod screenshot; use std::process::ExitCode; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; -use lutra_engine::{CommandInfo, ErrorPayload, theme}; +use lutra_engine::{CommandInfo, Engine, EngineConfig, ErrorPayload, Event, theme}; use serde_json::Value; use tauri::window::Color; -use tauri::{WebviewUrl, WebviewWindowBuilder}; +use tauri::{Manager, WebviewUrl, WebviewWindowBuilder}; use crate::host::{Host, MAIN_WINDOW, WINDOW_TITLE}; @@ -48,32 +48,28 @@ fn main() -> ExitCode { } } -/// Starts the host, the control channel and the Tauri event loop. +/// Builds the Tauri app, starts the engine with the app's config and data +/// directories, the host, the control channel, and runs the event loop. +/// The window is created in the setup hook, which runs once the event loop +/// has started. /// /// # Errors -/// A message if the engine cannot start, the control port cannot be bound, -/// or Tauri fails. +/// A message if Tauri cannot build the app or resolve its directories, the +/// engine cannot start, or the control port cannot be bound. fn run(args: &args::Args) -> Result<(), String> { - let host = Host::new().map_err(|e| e.to_string())?; - if let Some(port) = args.control { - let server = lutra_control::start(port, host.clone()) - .map_err(|e| format!("cannot serve the control channel on port {port}: {e}"))?; - eprintln!("lutra: control channel on {}", server.local_addr()); - } - host.start_pump() - .map_err(|e| format!("cannot start watching for changes: {e}"))?; + let slot: Arc>> = Arc::new(OnceLock::new()); + let setup_slot = slot.clone(); let theme = theme::DARK; - let setup_host = host.clone(); let initial_path = args.path.clone(); - tauri::Builder::default() + let app = tauri::Builder::default() .plugin(tauri_plugin_dialog::init()) - .manage(host) .invoke_handler(tauri::generate_handler![ engine_execute, engine_list_commands, engine_ready ]) .setup(move |app| { + let setup_host = setup_slot.get().ok_or("the host is not ready")?; setup_host.attach(app.handle().clone()); let mut window = WebviewWindowBuilder::new(app, MAIN_WINDOW, WebviewUrl::default()) .title(WINDOW_TITLE) @@ -91,8 +87,56 @@ fn run(args: &args::Args) -> Result<(), String> { } Ok(()) }) - .run(tauri::generate_context!()) - .map_err(|e| e.to_string()) + .build(tauri::generate_context!()) + .map_err(|e| e.to_string())?; + let mut engine = Engine::with_config(engine_config(&app)?).map_err(|e| e.to_string())?; + log_startup_events(&engine.take_events()); + let host = Host::new(engine); + app.manage(host.clone()); + if slot.set(host.clone()).is_err() { + return Err("the host was set twice".into()); + } + if let Some(port) = args.control { + let server = lutra_control::start(port, host.clone()) + .map_err(|e| format!("cannot serve the control channel on port {port}: {e}"))?; + eprintln!("lutra: control channel on {}", server.local_addr()); + } + host.start_pump() + .map_err(|e| format!("cannot start watching for changes: {e}"))?; + app.run(|_, _| {}); + Ok(()) +} + +/// The engine directories from Tauri's path resolver: the app config dir +/// for settings, the app data dir for the recovery journal. +/// +/// # Errors +/// A message if the platform has no such directories. +fn engine_config(app: &tauri::App) -> Result { + let paths = app.path(); + Ok(EngineConfig { + config_dir: paths + .app_config_dir() + .map_err(|e| format!("no config directory: {e}"))?, + data_dir: paths + .app_data_dir() + .map_err(|e| format!("no data directory: {e}"))?, + }) +} + +/// Logs the notifications the engine queued while starting, such as the +/// fallback to default settings, to stderr. +fn log_startup_events(events: &[Event]) { + for event in events { + if let Event::Notification { + level, + message: Some(message), + .. + } = event + { + eprintln!("lutra: {level:?}: {message}"); + } + } } /// Reads a `#rrggbb` theme token as an opaque colour for the window diff --git a/crates/control/tests/events.rs b/crates/control/tests/events.rs index 8da343b..77e0d80 100644 --- a/crates/control/tests/events.rs +++ b/crates/control/tests/events.rs @@ -147,6 +147,65 @@ fn streams_command_and_disk_events() { assert_eq!(client.event("treeChanged")["dir"], ""); } +#[test] +fn settings_changes_stream_and_persist() { + let dir = tempfile::tempdir().unwrap(); + let config = lutra_testkit::engine_config(dir.path()); + { + let backend = Arc::new(EngineBackend::with_config(config.clone())); + let server = lutra_control::start(0, backend.clone()).unwrap(); + let mut client = Client::connect(server.local_addr()); + client.call(json!({"id": 1, "method": "events.subscribe"})); + let r = client.call(execute( + "settings.set", + json!({"key": "editor.fontSize", "value": 16}), + )); + assert_eq!(r["result"]["value"], 16, "{r}"); + assert_eq!( + client.event("settingsChanged")["keys"], + json!(["editor.fontSize"]) + ); + let r = client.call(execute( + "settings.set", + json!({"key": "editor.fontSize", "value": 4}), + )); + assert_eq!(r["error"]["code"], "invalid_params"); + } + { + let backend = Arc::new(EngineBackend::with_config(config.clone())); + let server = lutra_control::start(0, backend.clone()).unwrap(); + let mut client = Client::connect(server.local_addr()); + let r = client.call(execute( + "settings.get", + json!({"keys": ["editor.fontSize"]}), + )); + assert_eq!(r["result"]["values"]["editor.fontSize"], 16, "{r}"); + } + + let file = config.config_dir.join("settings.json"); + std::fs::write(&file, "{\"editor.fontSize\": 16,,").unwrap(); + let backend = Arc::new(EngineBackend::with_config(config.clone())); + let server = lutra_control::start(0, backend.clone()).unwrap(); + let mut client = Client::connect(server.local_addr()); + client.call(json!({"id": 1, "method": "events.subscribe"})); + let r = client.call(execute("settings.get", Value::Null)); + assert_eq!( + r["result"]["values"], + json!({"appearance.theme": "system", "editor.fontSize": 14, "ui.language": "en"}), + "{r}" + ); + let notice = client.event("notification"); + assert_eq!(notice["level"], "warning"); + assert_eq!(notice["messageKey"], "notification.settings.corrupt"); + let backup = notice["params"]["backup"].as_str().unwrap(); + assert!(backup.starts_with("settings.json.bad-"), "{backup}"); + assert_eq!( + std::fs::read_to_string(config.config_dir.join(backup)).unwrap(), + "{\"editor.fontSize\": 16,," + ); + assert!(!file.exists()); +} + #[test] fn a_closed_connection_stops_receiving() { let backend = Arc::new(EngineBackend::new()); diff --git a/crates/engine/Cargo.toml b/crates/engine/Cargo.toml index 192936b..80c5bf1 100644 --- a/crates/engine/Cargo.toml +++ b/crates/engine/Cargo.toml @@ -22,4 +22,5 @@ thiserror = "2.0.21" workspace = true [dev-dependencies] +proptest.workspace = true tempfile.workspace = true diff --git a/crates/engine/src/cmd/mod.rs b/crates/engine/src/cmd/mod.rs index 6947bab..34744ad 100644 --- a/crates/engine/src/cmd/mod.rs +++ b/crates/engine/src/cmd/mod.rs @@ -5,6 +5,7 @@ mod buffer; mod file; mod params; mod project; +mod settings; use crate::{EngineError, Registry}; @@ -25,5 +26,9 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> { registry.register(Box::new(buffer::Get))?; registry.register(Box::new(buffer::Edit))?; registry.register(Box::new(buffer::Close))?; + registry.register(Box::new(settings::List))?; + registry.register(Box::new(settings::Get))?; + registry.register(Box::new(settings::Set))?; + registry.register(Box::new(settings::Reset))?; Ok(()) } diff --git a/crates/engine/src/cmd/settings.rs b/crates/engine/src/cmd/settings.rs new file mode 100644 index 0000000..1b353b3 --- /dev/null +++ b/crates/engine/src/cmd/settings.rs @@ -0,0 +1,159 @@ +//! Settings commands: `settings.list`, `settings.get`, `settings.set` and +//! `settings.reset`. Changes of an effective value emit `settingsChanged`. + +use serde::Deserialize; +use serde_json::{Map, Value, json}; + +use crate::cmd::params::parse; +use crate::settings::{self, DEFS, SetError}; +use crate::{Command, CommandSpec, EngineError, Event, Outcome, State}; + +/// `settings.list`: describes every known setting. +pub struct List; + +impl Command for List { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "settings.list", + label: "List Settings", + menu_path: None, + default_shortcut: None, + params: "none; returns [{ key, type: enum|int, default, enumValues?, min?, max?, labelKey, descriptionKey, section }]", + } + } + + fn run(&self, _state: &mut State, _params: Value) -> Result { + let list: Vec<_> = DEFS.iter().map(settings::Def::info).collect(); + let value = serde_json::to_value(list).map_err(|e| EngineError::Internal(e.to_string()))?; + Ok(Outcome::value(value)) + } +} + +/// Params of `settings.get`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct GetParams { + /// Keys to read; every known key when absent. + keys: Option>, +} + +/// `settings.get`: effective values of known settings. +pub struct Get; + +impl Command for Get { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "settings.get", + label: "Get Settings", + menu_path: None, + default_shortcut: None, + params: "{ keys?: string[] }; returns { values: { key: value } }, every setting without keys", + } + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let id = self.spec().id; + let p: GetParams = parse(id, params)?; + let keys: Vec = match p.keys { + Some(keys) => keys, + None => DEFS.iter().map(|d| d.key.to_string()).collect(), + }; + let mut values = Map::new(); + for key in keys { + let value = state.settings.get(&key).ok_or_else(|| { + EngineError::invalid_params(id, format!("unknown setting: {key}")) + })?; + values.insert(key, value); + } + Ok(Outcome::value(json!({ "values": values }))) + } +} + +/// Params of `settings.set`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct SetParams { + /// Setting key. + key: String, + /// New value. + value: Value, +} + +/// `settings.set`: validates and stores a value. +pub struct Set; + +impl Command for Set { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "settings.set", + label: "Change Setting", + menu_path: None, + default_shortcut: None, + params: "{ key, value }; returns { value }; invalid_params for an unknown key or a bad value", + } + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let id = self.spec().id; + let p: SetParams = parse(id, params)?; + let changed = state + .settings + .set(&p.key, p.value) + .map_err(|e| set_error(id, e))?; + finish(state, &p.key, changed) + } +} + +/// Params of `settings.reset`. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct ResetParams { + /// Setting key. + key: String, +} + +/// `settings.reset`: returns a setting to its default. +pub struct Reset; + +impl Command for Reset { + fn spec(&self) -> &CommandSpec { + &CommandSpec { + id: "settings.reset", + label: "Reset Setting", + menu_path: None, + default_shortcut: None, + params: "{ key }; returns { value } (the default); invalid_params for an unknown key", + } + } + + fn run(&self, state: &mut State, params: Value) -> Result { + let id = self.spec().id; + let p: ResetParams = parse(id, params)?; + let changed = state.settings.reset(&p.key).map_err(|e| set_error(id, e))?; + finish(state, &p.key, changed) + } +} + +/// Maps a settings error to the command error. +fn set_error(command: &str, error: SetError) -> EngineError { + match error { + SetError::Invalid(message) => EngineError::invalid_params(command, message), + SetError::Save(message) => { + EngineError::Failed(format!("cannot save the settings: {message}")) + } + } +} + +/// Emits `settingsChanged` if the value changed and returns `{ value }`. +fn finish(state: &mut State, key: &str, changed: bool) -> Result { + if changed { + state.emit(Event::SettingsChanged { + keys: vec![key.to_string()], + }); + } + let value = state + .settings + .get(key) + .ok_or_else(|| EngineError::Internal(format!("setting vanished: {key}")))?; + Ok(Outcome::value(json!({ "value": value }))) +} diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index 44fd043..12ce917 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -1,9 +1,24 @@ //! The engine: registry plus state, and the one entry point that runs //! commands. +use std::path::PathBuf; + use serde_json::Value; -use crate::{Command, CommandInfo, EngineError, Outcome, Registry, State, cmd, guard}; +use crate::settings::Settings; +use crate::{ + Command, CommandInfo, EngineError, NotificationLevel, Outcome, Registry, State, cmd, guard, +}; + +/// Where an engine stores its files. The desktop passes Tauri's app config +/// and app data directories; tests pass temp directories. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct EngineConfig { + /// User configuration: `settings.json`. + pub config_dir: PathBuf, + /// Application data, such as the crash-recovery journal. + pub data_dir: PathBuf, +} /// The command registry together with the workspace state. /// @@ -18,7 +33,33 @@ pub struct Engine { } impl Engine { - /// An engine with the built-in commands. + /// An engine with the built-in commands that stores its files in + /// `config`'s directories, and loads the settings. A missing settings + /// file gives the defaults. A corrupt or unreadable one never fails + /// construction: the defaults are used and a warning + /// [`crate::Event::Notification`] is queued; hosts take it with + /// [`Engine::take_events`]. + /// + /// # Errors + /// Returns [`EngineError::Internal`] if two built-in commands share an id. + pub fn with_config(config: EngineConfig) -> Result { + let mut engine = Self::new()?; + let (settings, problem) = Settings::load(&config.config_dir); + engine.state.settings = settings; + engine.state.config = Some(config); + if let Some(problem) = problem { + engine.state.notify( + NotificationLevel::Warning, + Some(problem.message_key()), + Some(problem.message()), + Some(problem.params()), + ); + } + Ok(engine) + } + + /// An engine with the built-in commands and no persistence: settings + /// live in memory only. For tests and the control-channel test backend. /// /// # Errors /// Returns [`EngineError::Internal`] if two built-in commands share an id. @@ -242,6 +283,10 @@ mod tests { "project.close", "project.open", "project.openDialog", + "settings.get", + "settings.list", + "settings.reset", + "settings.set", "test.disabled", ] ); diff --git a/crates/engine/src/event.rs b/crates/engine/src/event.rs index 1a3c9c4..5bda5a8 100644 --- a/crates/engine/src/event.rs +++ b/crates/engine/src/event.rs @@ -11,6 +11,7 @@ //! Paths are project-relative with `/` separators, the root is `""`. use serde::Serialize; +use serde_json::{Map, Value}; /// A state change. #[derive(Debug, Clone, PartialEq, Eq, Serialize)] @@ -76,13 +77,48 @@ pub enum Event { /// Why. message: String, }, + /// The effective value of settings changed; refetch them with + /// `settings.get`. + SettingsChanged { + /// The changed keys. + keys: Vec, + }, + /// A message for the user, shown as a toast. + Notification { + /// Unique id of this notification, for dismissing it. + id: String, + /// Severity. + level: NotificationLevel, + /// Message-catalog key of the text. + #[serde(skip_serializing_if = "Option::is_none")] + message_key: Option, + /// English text, for messages without a catalog key and as a + /// fallback. + #[serde(skip_serializing_if = "Option::is_none")] + message: Option, + /// Interpolation params for the catalog text. + #[serde(skip_serializing_if = "Option::is_none")] + params: Option>, + }, +} + +/// Severity of an [`Event::Notification`]. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +pub enum NotificationLevel { + /// Information; dismissed automatically. + Info, + /// Something went wrong but Lutra kept working. + Warning, + /// An action failed. + Error, } #[cfg(test)] mod tests { use serde_json::json; - use super::Event; + use super::{Event, NotificationLevel}; #[test] fn serialises_with_kind_and_camel_case_fields() { @@ -100,4 +136,34 @@ mod tests { json!({"kind": "projectClosed"}) ); } + + #[test] + fn notification_and_settings_shapes() { + let mut params = serde_json::Map::new(); + params.insert("backup".into(), json!("settings.json.bad-x")); + let n = Event::Notification { + id: "n1".into(), + level: NotificationLevel::Warning, + message_key: Some("notification.settings.corrupt".into()), + message: None, + params: Some(params), + }; + assert_eq!( + serde_json::to_value(n).unwrap(), + json!({ + "kind": "notification", + "id": "n1", + "level": "warning", + "messageKey": "notification.settings.corrupt", + "params": {"backup": "settings.json.bad-x"}, + }) + ); + assert_eq!( + serde_json::to_value(Event::SettingsChanged { + keys: vec!["editor.fontSize".into()] + }) + .unwrap(), + json!({"kind": "settingsChanged", "keys": ["editor.fontSize"]}) + ); + } } diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index a0b672f..42cda45 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -13,14 +13,15 @@ mod error; mod event; pub mod guard; mod registry; +pub mod settings; mod state; pub mod theme; pub mod workspace; pub use buffers::{BufferId, LineEndingName, OpenBuffer}; pub use command::{Command, CommandInfo, CommandSpec, Effect, Outcome}; -pub use engine::Engine; +pub use engine::{Engine, EngineConfig}; pub use error::{EngineError, ErrorPayload}; -pub use event::Event; +pub use event::{Event, NotificationLevel}; pub use registry::Registry; pub use state::State; diff --git a/crates/engine/src/settings.rs b/crates/engine/src/settings.rs new file mode 100644 index 0000000..8b49672 --- /dev/null +++ b/crates/engine/src/settings.rs @@ -0,0 +1,669 @@ +//! Settings: the known keys with their types and defaults, typed +//! validation, and persistence in `/settings.json`. +//! +//! The file is a flat JSON object (`{"editor.fontSize": 16}`). It is +//! untrusted: it is read with a size cap of [`MAX_FILE_SIZE`], a value that +//! fails validation counts as unset, and keys Lutra does not know are kept +//! untouched when the file is written again. A file that cannot be parsed is +//! moved aside to `settings.json.bad-` and the defaults are used, +//! so a broken file never blocks startup. + +use std::fs::{self, File}; +use std::io::{self, Read}; +use std::path::{Path, PathBuf}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use serde::Serialize; +use serde_json::{Map, Value}; + +/// Name of the settings file inside the config directory. +pub const FILE_NAME: &str = "settings.json"; + +/// Largest settings file that is read; a larger one counts as corrupt. +pub const MAX_FILE_SIZE: u64 = 1024 * 1024; + +/// The type of a setting and what values it accepts. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Kind { + /// One of a fixed list of strings. + Enum(&'static [&'static str]), + /// An integer in `min..=max`. + Int { + /// Smallest allowed value. + min: i64, + /// Largest allowed value. + max: i64, + }, +} + +/// The default value of a setting. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum DefaultValue { + /// A string, for [`Kind::Enum`]. + Str(&'static str), + /// An integer, for [`Kind::Int`]. + Int(i64), +} + +impl DefaultValue { + /// The default as JSON. + pub fn to_value(self) -> Value { + match self { + Self::Str(s) => Value::from(s), + Self::Int(i) => Value::from(i), + } + } +} + +/// A known setting. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Def { + /// Dotted key, e.g. `editor.fontSize`. + pub key: &'static str, + /// Type and accepted values. + pub kind: Kind, + /// Value used while the setting is unset or its stored value is invalid. + pub default: DefaultValue, + /// Message-catalog key of the label. + pub label_key: &'static str, + /// Message-catalog key of the description. + pub description_key: &'static str, + /// Section id; the UI shows it with the catalog key + /// `settings.section.
`. + pub section: &'static str, +} + +impl Def { + /// Whether `value` is valid for this setting. + pub fn accepts(&self, value: &Value) -> bool { + self.check(value).is_ok() + } + + /// Checks `value` against the setting's type. + /// + /// # Errors + /// A message saying what is wrong with the value, for `invalid_params`. + pub fn check(&self, value: &Value) -> Result<(), String> { + match self.kind { + Kind::Enum(values) => match value.as_str() { + Some(s) if values.contains(&s) => Ok(()), + _ => Err(format!( + "{} must be one of {}, got {value}", + self.key, + values.join(", ") + )), + }, + Kind::Int { min, max } => match value.as_i64() { + Some(i) if (min..=max).contains(&i) => Ok(()), + _ => Err(format!( + "{} must be an integer from {min} to {max}, got {value}", + self.key + )), + }, + } + } + + /// The description for `settings.list`. + pub fn info(&self) -> SettingInfo { + let (kind, enum_values, min, max) = match self.kind { + Kind::Enum(values) => ("enum", Some(values.to_vec()), None, None), + Kind::Int { min, max } => ("int", None, Some(min), Some(max)), + }; + SettingInfo { + key: self.key, + kind, + default: self.default.to_value(), + enum_values, + min, + max, + label_key: self.label_key, + description_key: self.description_key, + section: self.section, + } + } +} + +/// One entry of `settings.list`. +#[derive(Debug, Clone, PartialEq, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct SettingInfo { + /// Dotted key. + pub key: &'static str, + /// `enum` or `int`. + #[serde(rename = "type")] + pub kind: &'static str, + /// Default value. + pub default: Value, + /// Accepted values of an enum. + #[serde(skip_serializing_if = "Option::is_none")] + pub enum_values: Option>, + /// Smallest value of an int. + #[serde(skip_serializing_if = "Option::is_none")] + pub min: Option, + /// Largest value of an int. + #[serde(skip_serializing_if = "Option::is_none")] + pub max: Option, + /// Catalog key of the label. + pub label_key: &'static str, + /// Catalog key of the description. + pub description_key: &'static str, + /// Section id. + pub section: &'static str, +} + +/// Every known setting, in display order. +pub const DEFS: &[Def] = &[ + Def { + key: "appearance.theme", + kind: Kind::Enum(&["lutra-dark", "lutra-light", "system"]), + default: DefaultValue::Str("system"), + label_key: "settings.appearance.theme.label", + description_key: "settings.appearance.theme.description", + section: "appearance", + }, + Def { + key: "editor.fontSize", + kind: Kind::Int { min: 8, max: 48 }, + default: DefaultValue::Int(14), + label_key: "settings.editor.fontSize.label", + description_key: "settings.editor.fontSize.description", + section: "editor", + }, + Def { + key: "ui.language", + kind: Kind::Enum(&["en"]), + default: DefaultValue::Str("en"), + label_key: "settings.ui.language.label", + description_key: "settings.ui.language.description", + section: "appearance", + }, +]; + +/// Looks a known setting up by key. +pub fn def(key: &str) -> Option<&'static Def> { + DEFS.iter().find(|d| d.key == key) +} + +/// Why loading the settings file did not give the stored values. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum LoadProblem { + /// The file was unreadable as settings and was moved to `backup`. + Corrupt { + /// What was wrong with it. + reason: String, + /// File name of the backup in the config directory. + backup: String, + }, + /// The file was unreadable as settings and could not be moved aside; + /// it is left alone and settings are not saved this session. + CorruptNotMoved { + /// What was wrong with it. + reason: String, + /// Why it could not be moved. + error: String, + }, + /// The file or the config directory could not be accessed; settings + /// are not saved this session. + Unavailable { + /// The I/O error. + error: String, + }, +} + +impl LoadProblem { + /// English text for logs and for notifications without a catalog entry. + pub fn message(&self) -> String { + match self { + Self::Corrupt { reason, backup } => format!( + "settings.json could not be read ({reason}); it was moved to {backup} and the defaults are used" + ), + Self::CorruptNotMoved { reason, error } => format!( + "settings.json could not be read ({reason}) or moved aside ({error}); the defaults are used and changes are not saved" + ), + Self::Unavailable { error } => format!( + "settings cannot be loaded ({error}); the defaults are used and changes are not saved" + ), + } + } + + /// Message-catalog key for the notification. + pub fn message_key(&self) -> &'static str { + match self { + Self::Corrupt { .. } => "notification.settings.corrupt", + Self::CorruptNotMoved { .. } => "notification.settings.corruptNotMoved", + Self::Unavailable { .. } => "notification.settings.unavailable", + } + } + + /// Interpolation params for the catalog message. + pub fn params(&self) -> Map { + let mut params = Map::new(); + match self { + Self::Corrupt { reason, backup } => { + params.insert("reason".into(), Value::from(reason.as_str())); + params.insert("backup".into(), Value::from(backup.as_str())); + } + Self::CorruptNotMoved { reason, error } => { + params.insert("reason".into(), Value::from(reason.as_str())); + params.insert("error".into(), Value::from(error.as_str())); + } + Self::Unavailable { error } => { + params.insert("error".into(), Value::from(error.as_str())); + } + } + params + } +} + +/// The settings of the running engine. +#[derive(Debug, Clone, PartialEq, Default)] +pub struct Settings { + /// The settings file; `None` keeps settings in memory only. + file: Option, + /// The stored object, unknown keys and invalid values included. + stored: Map, +} + +impl Settings { + /// Settings kept in memory only, all at their defaults. + pub fn in_memory() -> Self { + Self::default() + } + + /// Loads `/settings.json`, creating the directory if needed. + /// A missing file gives the defaults. Never fails: every problem is + /// returned next to settings that work (the defaults, in memory only + /// when the file cannot safely be written). + pub fn load(config_dir: &Path) -> (Self, Option) { + if let Err(e) = fs::create_dir_all(config_dir) { + return ( + Self::in_memory(), + Some(LoadProblem::Unavailable { + error: format!("{}: {e}", config_dir.display()), + }), + ); + } + let file = config_dir.join(FILE_NAME); + let bytes = match read_capped(&file) { + Ok(Some(bytes)) => bytes, + Ok(None) => return (Self::persistent(file, Map::new()), None), + Err(ReadError::TooLarge) => { + return Self::recover(file, format!("larger than {MAX_FILE_SIZE} bytes")); + } + Err(ReadError::Io(e)) => { + return ( + Self::in_memory(), + Some(LoadProblem::Unavailable { + error: format!("{}: {e}", file.display()), + }), + ); + } + }; + match parse(&bytes) { + Ok(stored) => (Self::persistent(file, stored), None), + Err(reason) => Self::recover(file, reason), + } + } + + /// Settings backed by `file` with the given stored object. + fn persistent(file: PathBuf, stored: Map) -> Self { + Self { + file: Some(file), + stored, + } + } + + /// Moves a corrupt file aside and returns the defaults: persistent if + /// the move worked, in memory otherwise so the file is not overwritten. + fn recover(file: PathBuf, reason: String) -> (Self, Option) { + match backup(&file) { + Ok(backup) => ( + Self::persistent(file, Map::new()), + Some(LoadProblem::Corrupt { reason, backup }), + ), + Err(e) => ( + Self::in_memory(), + Some(LoadProblem::CorruptNotMoved { + reason, + error: e.to_string(), + }), + ), + } + } + + /// The settings file, if settings are saved. + pub fn file(&self) -> Option<&Path> { + self.file.as_deref() + } + + /// The effective value of a known key: the stored value if it is valid, + /// otherwise the default. `None` for an unknown key. + pub fn get(&self, key: &str) -> Option { + let def = def(key)?; + Some( + self.stored + .get(key) + .filter(|v| def.accepts(v)) + .cloned() + .unwrap_or_else(|| def.default.to_value()), + ) + } + + /// Stores `value` for `key` and saves the file. Nothing changes if + /// validation or saving fails. + /// + /// Returns whether the effective value changed. + /// + /// # Errors + /// [`SetError::Invalid`] for an unknown key or a bad value, + /// [`SetError::Save`] if the file cannot be written. + pub fn set(&mut self, key: &str, value: Value) -> Result { + let def = def(key).ok_or_else(|| SetError::Invalid(format!("unknown setting: {key}")))?; + def.check(&value).map_err(SetError::Invalid)?; + let mut stored = self.stored.clone(); + stored.insert(key.to_string(), value); + self.commit(key, stored) + } + + /// Removes the stored value of `key`, so the default applies, and saves + /// the file. Returns whether the effective value changed. + /// + /// # Errors + /// [`SetError::Invalid`] for an unknown key, [`SetError::Save`] if the + /// file cannot be written. + pub fn reset(&mut self, key: &str) -> Result { + if def(key).is_none() { + return Err(SetError::Invalid(format!("unknown setting: {key}"))); + } + if !self.stored.contains_key(key) { + return Ok(false); + } + let mut stored = self.stored.clone(); + stored.remove(key); + self.commit(key, stored) + } + + /// Saves `stored` and makes it current; returns whether `key`'s + /// effective value changed. + fn commit(&mut self, key: &str, stored: Map) -> Result { + let before = self.get(key); + if let Some(file) = &self.file { + let mut text = + serde_json::to_string_pretty(&stored).map_err(|e| SetError::Save(e.to_string()))?; + text.push('\n'); + lutra_vfs::write_atomic(file, text.as_bytes()) + .map_err(|e| SetError::Save(e.to_string()))?; + } + self.stored = stored; + Ok(self.get(key) != before) + } +} + +/// Why `set` or `reset` failed. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum SetError { + /// Unknown key or bad value. + Invalid(String), + /// The file could not be written. + Save(String), +} + +/// Why reading the file failed. +enum ReadError { + /// Larger than [`MAX_FILE_SIZE`]. + TooLarge, + /// Any other I/O error. + Io(io::Error), +} + +/// Reads at most [`MAX_FILE_SIZE`] bytes of `file`; `None` if it does not +/// exist. +fn read_capped(file: &Path) -> Result>, ReadError> { + let handle = match File::open(file) { + Ok(handle) => handle, + Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(None), + Err(e) => return Err(ReadError::Io(e)), + }; + let mut bytes = Vec::new(); + handle + .take(MAX_FILE_SIZE.saturating_add(1)) + .read_to_end(&mut bytes) + .map_err(ReadError::Io)?; + if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > MAX_FILE_SIZE { + return Err(ReadError::TooLarge); + } + Ok(Some(bytes)) +} + +/// Parses the file content into the stored object. +/// +/// # Errors +/// Why the content is not a JSON object. +fn parse(bytes: &[u8]) -> Result, String> { + match serde_json::from_slice::(bytes) { + Ok(Value::Object(map)) => Ok(map), + Ok(_) => Err("not a JSON object".into()), + Err(e) => Err(format!("invalid JSON: {e}")), + } +} + +/// Renames `file` to `settings.json.bad-` next to it, adding +/// `-1`, `-2`… if that name is taken. Returns the new file name. +fn backup(file: &Path) -> io::Result { + let stamp = timestamp(SystemTime::now()); + for n in 0..100u32 { + let name = if n == 0 { + format!("{FILE_NAME}.bad-{stamp}") + } else { + format!("{FILE_NAME}.bad-{stamp}-{n}") + }; + let target = file.with_file_name(&name); + if target.exists() { + continue; + } + fs::rename(file, &target)?; + return Ok(name); + } + Err(io::Error::new( + io::ErrorKind::AlreadyExists, + "too many backups with the same timestamp", + )) +} + +/// Formats a time as `YYYYMMDDTHHMMSSZ` in UTC; times before 1970 count as +/// 1970-01-01. +fn timestamp(time: SystemTime) -> String { + let secs = time + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs()) + .unwrap_or(0); + let days = i64::try_from(secs / 86_400).unwrap_or(0); + let rem = secs % 86_400; + let (y, m, d) = civil_from_days(days); + format!( + "{y:04}{m:02}{d:02}T{:02}{:02}{:02}Z", + rem / 3600, + rem % 3600 / 60, + rem % 60 + ) +} + +/// Converts days since 1970-01-01 to a proleptic Gregorian date +/// (H. Hinnant's `civil_from_days`). +fn civil_from_days(days: i64) -> (i64, i64, i64) { + let z = days + 719_468; + let era = z.div_euclid(146_097); + let doe = z.rem_euclid(146_097); + let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; + let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); + let mp = (5 * doy + 2) / 153; + let d = doy - (153 * mp + 2) / 5 + 1; + let m = if mp < 10 { mp + 3 } else { mp - 9 }; + let y = yoe + era * 400 + i64::from(m <= 2); + (y, m, d) +} + +#[cfg(test)] +mod tests { + use std::time::Duration; + + use serde_json::json; + + use super::*; + + #[test] + fn defaults_and_validation() { + let mut s = Settings::in_memory(); + assert_eq!(s.get("appearance.theme"), Some(json!("system"))); + assert_eq!(s.get("editor.fontSize"), Some(json!(14))); + assert_eq!(s.get("ui.language"), Some(json!("en"))); + assert_eq!(s.get("nope"), None); + assert_eq!(s.set("editor.fontSize", json!(16)), Ok(true)); + assert_eq!(s.set("editor.fontSize", json!(16)), Ok(false)); + for bad in [json!(7), json!(49), json!(16.5), json!("16"), json!(null)] { + assert!(matches!( + s.set("editor.fontSize", bad), + Err(SetError::Invalid(_)) + )); + } + assert!(matches!( + s.set("appearance.theme", json!("dark")), + Err(SetError::Invalid(_)) + )); + assert!(matches!(s.set("x.y", json!(1)), Err(SetError::Invalid(_)))); + assert_eq!(s.get("editor.fontSize"), Some(json!(16))); + assert_eq!(s.reset("editor.fontSize"), Ok(true)); + assert_eq!(s.reset("editor.fontSize"), Ok(false)); + assert_eq!(s.get("editor.fontSize"), Some(json!(14))); + } + + #[test] + fn every_default_is_valid() { + for d in DEFS { + assert!(d.accepts(&d.default.to_value()), "{}", d.key); + } + } + + #[test] + fn list_info_shape() { + let theme = serde_json::to_value(DEFS[0].info()).unwrap(); + assert_eq!( + theme, + json!({ + "key": "appearance.theme", + "type": "enum", + "default": "system", + "enumValues": ["lutra-dark", "lutra-light", "system"], + "labelKey": "settings.appearance.theme.label", + "descriptionKey": "settings.appearance.theme.description", + "section": "appearance", + }) + ); + let size = serde_json::to_value(DEFS[1].info()).unwrap(); + assert_eq!(size["min"], 8); + assert_eq!(size["max"], 48); + assert!(size.get("enumValues").is_none()); + } + + #[test] + fn formats_utc_timestamps() { + assert_eq!(timestamp(UNIX_EPOCH), "19700101T000000Z"); + let t = UNIX_EPOCH + Duration::from_secs(1_760_554_920); + assert_eq!(timestamp(t), "20251015T190200Z"); + let leap = UNIX_EPOCH + Duration::from_secs(951_782_400); + assert_eq!(timestamp(leap), "20000229T000000Z"); + } + + #[test] + fn keeps_unknown_keys_and_ignores_invalid_values() { + let dir = tempfile::tempdir().unwrap(); + let file = dir.path().join(FILE_NAME); + fs::write( + &file, + r#"{"future.key": [1, 2], "editor.fontSize": 400, "appearance.theme": "lutra-light"}"#, + ) + .unwrap(); + let (mut s, problem) = Settings::load(dir.path()); + assert_eq!(problem, None); + assert_eq!(s.get("editor.fontSize"), Some(json!(14))); + assert_eq!(s.get("appearance.theme"), Some(json!("lutra-light"))); + assert_eq!(s.set("editor.fontSize", json!(20)), Ok(true)); + let saved: Value = serde_json::from_str(&fs::read_to_string(&file).unwrap()).unwrap(); + assert_eq!( + saved, + json!({"future.key": [1, 2], "editor.fontSize": 20, "appearance.theme": "lutra-light"}) + ); + } + + #[test] + fn corrupt_file_is_moved_aside() { + let dir = tempfile::tempdir().unwrap(); + let file = dir.path().join(FILE_NAME); + fs::write(&file, "{not json").unwrap(); + let (mut s, problem) = Settings::load(dir.path()); + let Some(LoadProblem::Corrupt { backup, .. }) = problem else { + panic!("expected Corrupt, got {problem:?}"); + }; + assert!(backup.starts_with("settings.json.bad-")); + assert_eq!( + fs::read_to_string(dir.path().join(&backup)).unwrap(), + "{not json" + ); + assert!(!file.exists()); + assert_eq!(s.get("editor.fontSize"), Some(json!(14))); + s.set("editor.fontSize", json!(9)).unwrap(); + assert!(file.exists()); + } + + #[test] + fn non_objects_and_huge_files_are_corrupt() { + for content in [ + b"[1,2]".to_vec(), + b"\xff\xfe".to_vec(), + vec![b' '; 1024 * 1024 + 1], + ] { + let dir = tempfile::tempdir().unwrap(); + fs::write(dir.path().join(FILE_NAME), &content).unwrap(); + let (s, problem) = Settings::load(dir.path()); + assert!( + matches!(problem, Some(LoadProblem::Corrupt { .. })), + "{problem:?}" + ); + assert!(s.file().is_some()); + } + } + + #[test] + fn second_backup_in_the_same_second_gets_a_suffix() { + let dir = tempfile::tempdir().unwrap(); + let file = dir.path().join(FILE_NAME); + fs::write(&file, "1").unwrap(); + let first = backup(&file).unwrap(); + fs::write(&file, "2").unwrap(); + let second = backup(&file).unwrap(); + assert_ne!(first, second); + assert!(dir.path().join(first).exists()); + assert!(dir.path().join(second).exists()); + } + + #[test] + fn unusable_config_dir_keeps_settings_in_memory() { + let dir = tempfile::tempdir().unwrap(); + let blocker = dir.path().join("file"); + fs::write(&blocker, "x").unwrap(); + let (mut s, problem) = Settings::load(&blocker.join("config")); + assert!(matches!(problem, Some(LoadProblem::Unavailable { .. }))); + assert_eq!(s.file(), None); + assert_eq!(s.set("editor.fontSize", json!(30)), Ok(true)); + } + + #[test] + fn a_directory_in_place_of_the_file_is_not_touched() { + let dir = tempfile::tempdir().unwrap(); + fs::create_dir(dir.path().join(FILE_NAME)).unwrap(); + let (s, problem) = Settings::load(dir.path()); + assert!(problem.is_some(), "{problem:?}"); + assert_eq!(s.file(), None); + assert!(dir.path().join(FILE_NAME).is_dir()); + } +} diff --git a/crates/engine/src/state.rs b/crates/engine/src/state.rs index 0ea9a3f..3af2aff 100644 --- a/crates/engine/src/state.rs +++ b/crates/engine/src/state.rs @@ -1,8 +1,11 @@ //! Workspace state that commands read and change. -use crate::Event; +use serde_json::{Map, Value}; + use crate::buffers::Buffers; +use crate::settings::Settings; use crate::workspace::Workspace; +use crate::{EngineConfig, Event, NotificationLevel}; /// Everything the engine knows about the running session. #[derive(Debug, Default)] @@ -13,6 +16,13 @@ pub struct State { pub project: Option, /// Open buffers. Empty whenever no project is open. pub buffers: Buffers, + /// Settings, saved to the config directory when the engine has one. + pub settings: Settings, + /// Where the engine stores its files; `None` for an engine without + /// persistence ([`crate::Engine::new`]). + pub config: Option, + /// Number of notifications emitted, for their ids. + notifications: u64, /// Events queued for the host, oldest first. events: Vec, } @@ -23,6 +33,24 @@ impl State { self.events.push(event); } + /// Queues an [`Event::Notification`] with a fresh id (`n1`, `n2`…). + pub fn notify( + &mut self, + level: NotificationLevel, + message_key: Option<&str>, + message: Option, + params: Option>, + ) { + self.notifications = self.notifications.saturating_add(1); + self.emit(Event::Notification { + id: format!("n{}", self.notifications), + level, + message_key: message_key.map(str::to_string), + message, + params, + }); + } + /// Takes the queued events, oldest first. pub fn take_events(&mut self) -> Vec { std::mem::take(&mut self.events) diff --git a/crates/engine/tests/settings.rs b/crates/engine/tests/settings.rs new file mode 100644 index 0000000..bfe3176 --- /dev/null +++ b/crates/engine/tests/settings.rs @@ -0,0 +1,254 @@ +//! Settings commands, persistence across engines, corrupt files, and a +//! property test over random `settings.json` content. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::indexing_slicing +)] + +use std::fs; + +use lutra_engine::settings::{DEFS, FILE_NAME}; +use lutra_engine::{Engine, EngineConfig, Event, NotificationLevel}; +use proptest::prelude::*; +use serde_json::{Value, json}; +use tempfile::TempDir; + +fn config(dir: &TempDir) -> EngineConfig { + EngineConfig { + config_dir: dir.path().join("config"), + data_dir: dir.path().join("data"), + } +} + +fn engine(dir: &TempDir) -> Engine { + Engine::with_config(config(dir)).unwrap() +} + +fn get_all(engine: &mut Engine) -> Value { + engine.execute("settings.get", Value::Null).unwrap().value["values"].clone() +} + +#[test] +fn list_describes_the_c2_keys_with_catalog_keys_only() { + let mut e = Engine::new().unwrap(); + let list = e.execute("settings.list", Value::Null).unwrap().value; + let keys: Vec<_> = list + .as_array() + .unwrap() + .iter() + .map(|s| s["key"].as_str().unwrap()) + .collect(); + assert_eq!(keys, ["appearance.theme", "editor.fontSize", "ui.language"]); + for s in list.as_array().unwrap() { + assert!(s.get("label").is_none()); + assert!(s["labelKey"].as_str().unwrap().starts_with("settings.")); + assert!( + s["descriptionKey"] + .as_str() + .unwrap() + .ends_with(".description") + ); + } + assert_eq!(list[1]["type"], "int"); + assert_eq!(list[1]["default"], 14); + assert_eq!(list[2]["enumValues"], json!(["en"])); +} + +#[test] +fn get_set_reset_and_events() { + let mut e = Engine::new().unwrap(); + assert_eq!( + get_all(&mut e), + json!({"appearance.theme": "system", "editor.fontSize": 14, "ui.language": "en"}) + ); + let out = e + .execute( + "settings.set", + json!({"key": "appearance.theme", "value": "lutra-light"}), + ) + .unwrap(); + assert_eq!(out.value, json!({"value": "lutra-light"})); + assert_eq!( + out.events, + vec![Event::SettingsChanged { + keys: vec!["appearance.theme".into()] + }] + ); + let same = e + .execute( + "settings.set", + json!({"key": "appearance.theme", "value": "lutra-light"}), + ) + .unwrap(); + assert!(same.events.is_empty()); + let got = e + .execute("settings.get", json!({"keys": ["appearance.theme"]})) + .unwrap() + .value; + assert_eq!(got, json!({"values": {"appearance.theme": "lutra-light"}})); + + let reset = e + .execute("settings.reset", json!({"key": "appearance.theme"})) + .unwrap(); + assert_eq!(reset.value, json!({"value": "system"})); + assert_eq!(reset.events.len(), 1); + let again = e + .execute("settings.reset", json!({"key": "appearance.theme"})) + .unwrap(); + assert!(again.events.is_empty()); +} + +#[test] +fn bad_params_are_invalid_params() { + let mut e = Engine::new().unwrap(); + for (command, params) in [ + ( + "settings.set", + json!({"key": "editor.fontSize", "value": 100}), + ), + ( + "settings.set", + json!({"key": "editor.fontSize", "value": "16"}), + ), + ("settings.set", json!({"key": "ui.language", "value": "de"})), + ("settings.set", json!({"key": "nope", "value": 1})), + ("settings.set", json!({"key": "editor.fontSize"})), + ("settings.reset", json!({"key": "nope"})), + ("settings.get", json!({"keys": ["nope"]})), + ("settings.get", json!({"keys": "editor.fontSize"})), + ] { + let err = e.execute(command, params.clone()).unwrap_err(); + assert_eq!(err.code(), "invalid_params", "{command} {params}"); + } + assert!(e.take_events().is_empty()); + assert_eq!(get_all(&mut e)["editor.fontSize"], 14); +} + +#[test] +fn values_survive_a_restart() { + let dir = tempfile::tempdir().unwrap(); + { + let mut e = engine(&dir); + assert!(e.take_events().is_empty(), "a missing file is no problem"); + e.execute( + "settings.set", + json!({"key": "editor.fontSize", "value": 16}), + ) + .unwrap(); + } + let file = dir.path().join("config").join(FILE_NAME); + let saved: Value = serde_json::from_str(&fs::read_to_string(&file).unwrap()).unwrap(); + assert_eq!(saved, json!({"editor.fontSize": 16})); + let mut e = engine(&dir); + assert_eq!(get_all(&mut e)["editor.fontSize"], 16); + assert_eq!(e.state().config, Some(config(&dir))); +} + +#[test] +fn a_corrupt_file_is_backed_up_and_reported() { + let dir = tempfile::tempdir().unwrap(); + let config_dir = dir.path().join("config"); + fs::create_dir_all(&config_dir).unwrap(); + fs::write(config_dir.join(FILE_NAME), "{\"editor.fontSize\": 16,").unwrap(); + let mut e = engine(&dir); + let events = e.take_events(); + let [ + Event::Notification { + level, + message_key, + message, + params, + .. + }, + ] = events.as_slice() + else { + panic!("expected one notification, got {events:?}"); + }; + assert_eq!(*level, NotificationLevel::Warning); + assert_eq!( + message_key.as_deref(), + Some("notification.settings.corrupt") + ); + assert!(message.as_deref().unwrap().contains("defaults")); + let backup = params.as_ref().unwrap()["backup"].as_str().unwrap(); + assert!(backup.starts_with("settings.json.bad-"), "{backup}"); + assert_eq!( + fs::read_to_string(config_dir.join(backup)).unwrap(), + "{\"editor.fontSize\": 16," + ); + assert_eq!(get_all(&mut e)["editor.fontSize"], 14); +} + +#[test] +fn engine_new_has_no_persistence() { + let e = Engine::new().unwrap(); + assert_eq!(e.state().config, None); + assert_eq!(e.state().settings.file(), None); +} + +/// Arbitrary JSON values, nested a few levels. +fn json_value() -> impl Strategy { + let leaf = prop_oneof![ + Just(Value::Null), + any::().prop_map(Value::from), + any::().prop_map(Value::from), + any::() + .prop_map(|f| serde_json::Number::from_f64(f).map_or(Value::Null, Value::Number)), + "[a-z.\\-]{0,12}".prop_map(Value::from), + prop::sample::select(vec!["lutra-dark", "lutra-light", "system", "en", "de"]) + .prop_map(Value::from), + (0i64..64).prop_map(Value::from), + ]; + leaf.prop_recursive(3, 24, 4, |inner| { + prop_oneof![ + prop::collection::vec(inner.clone(), 0..4).prop_map(Value::from), + prop::collection::btree_map(key(), inner, 0..4) + .prop_map(|m| Value::Object(m.into_iter().collect())), + ] + }) +} + +/// Keys that are often known settings. +fn key() -> impl Strategy { + prop_oneof![ + prop::sample::select(DEFS.iter().map(|d| d.key.to_string()).collect::>()), + "[a-zA-Z.]{0,10}", + ] +} + +/// File content: random bytes, random JSON, or an object of known keys. +fn content() -> impl Strategy> { + prop_oneof![ + prop::collection::vec(any::(), 0..64), + json_value().prop_map(|v| v.to_string().into_bytes()), + prop::collection::btree_map(key(), json_value(), 0..6).prop_map(|m| { + Value::Object(m.into_iter().collect()) + .to_string() + .into_bytes() + }), + ] +} + +proptest! { + #![proptest_config(ProptestConfig::with_cases(128))] + + #[test] + fn random_files_never_panic_and_give_valid_values(bytes in content()) { + let dir = tempfile::tempdir().unwrap(); + let config_dir = dir.path().join("config"); + fs::create_dir_all(&config_dir).unwrap(); + fs::write(config_dir.join(FILE_NAME), &bytes).unwrap(); + let mut e = engine(&dir); + let values = get_all(&mut e); + for def in DEFS { + prop_assert!(def.accepts(&values[def.key]), "{} = {}", def.key, values[def.key]); + } + let set = e.execute("settings.set", json!({"key": "editor.fontSize", "value": 20})); + prop_assert!(set.is_ok()); + let mut again = engine(&dir); + prop_assert_eq!(&get_all(&mut again)["editor.fontSize"], &json!(20)); + } +} diff --git a/crates/testkit/src/lib.rs b/crates/testkit/src/lib.rs index 7ceddc9..3e117e6 100644 --- a/crates/testkit/src/lib.rs +++ b/crates/testkit/src/lib.rs @@ -14,9 +14,18 @@ use std::path::{Path, PathBuf}; use std::sync::Mutex; use lutra_control::{Backend, EventSink, Subscribers}; -use lutra_engine::{CommandInfo, Effect, Engine, EngineError}; +use lutra_engine::{CommandInfo, Effect, Engine, EngineConfig, EngineError}; use serde_json::Value; +/// Engine directories inside `root` (`root/config`, `root/data`), for +/// [`Engine::with_config`] and [`EngineBackend::with_config`] in tests. +pub fn engine_config(root: &Path) -> EngineConfig { + EngineConfig { + config_dir: root.join("config"), + data_dir: root.join("data"), + } +} + /// A control [`Backend`] over a bare engine, without a window. /// /// Effects are recorded instead of applied; events are published to @@ -34,10 +43,22 @@ pub struct EngineBackend { } impl EngineBackend { - /// A backend with the built-in commands. + /// A backend with the built-in commands and no persistence. pub fn new() -> Self { + Self::with_engine(Engine::new().unwrap()) + } + + /// A backend whose engine stores its files in `config`, like the + /// desktop app. Events queued while the engine started (a settings + /// warning) stay queued and arrive with the first command or pump. + pub fn with_config(config: EngineConfig) -> Self { + Self::with_engine(Engine::with_config(config).unwrap()) + } + + /// A backend around an existing engine. + pub fn with_engine(engine: Engine) -> Self { Self { - engine: Mutex::new(Engine::new().unwrap()), + engine: Mutex::new(engine), effects: Mutex::new(Vec::new()), screenshots: Mutex::new(Vec::new()), subscribers: Subscribers::default(), diff --git a/docs/architecture.md b/docs/architecture.md index c2490f5..cce816b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # Architecture -> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor documented · **Last updated:** 2026-10-15 +> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, engine construction and settings documented · **Last updated:** 2026-10-16 ## Overview @@ -101,6 +101,19 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat - 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. Tokens the theme does not have yet are read as `var(--lt-new-token, )` so they take effect once added in Rust. +### Engine construction (M1.9a) + +- `EngineConfig { config_dir, data_dir }` and `Engine::with_config(config) -> Result`. 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 logs them to stderr (the UI does not see startup notifications yet, M1.12). + +### Settings (M1.9a) + +- `/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-` (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..label` / `.description`; `section` is an id shown with `settings.section.`), `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`…). + ## Decisions (M0) | Question | Decision | Why | @@ -118,6 +131,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat | Date | Change | Summary | |---|---|---| +| 2026-10-16 | minor | M1.9a: engine construction (EngineConfig, with_config) and settings (file, commands, settingsChanged, notification) | | 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 | diff --git a/docs/gaps.md b/docs/gaps.md index cfea08b..81df845 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -1,6 +1,6 @@ # Gaps -> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app); G3 project tree works in the app · **Last updated:** 2026-10-15 +> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app); G3 project tree works in the app, settings backend landed · **Last updated:** 2026-10-16 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. @@ -8,7 +8,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t |---|---|---|---| | G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) | | G2 | Editor core: ~~engine buffers, save~~ (M1.3), ~~editor UI with tabs, undo, multi-caret~~ (M1.6, CodeMirror basics), recovery journal, tab management (preview, pin, split, close others, reopen), conflict UI for files changed on disk, autosave option | M1 | ~18 h | -| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, showing truncated listings, error notifications for the folder picker, ~~tabs~~ (M1.6); command palette, settings, theme switching | M1 | ~24 h | +| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, showing truncated listings, error notifications for the folder picker, ~~tabs~~ (M1.6); command palette, settings (backend: M1.9a; dialog: M1.9b), theme switching | M1 | ~24 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 | @@ -36,6 +36,7 @@ Known smaller items from M0: | Date | Change | Summary | |---|---|---| | 2026-10-15 | minor | G2 shrunk: tabs and editor (M1.6) | +| 2026-10-16 | minor | G3: settings backend (M1.9a) | | 2026-10-15 | minor | G3 shrunk: project tree wired to the engine (M1.4) | | 2026-10-14 | minor | G2 shrunk, G3 note: engine workspace (M1.3) | | 2026-10-14 | minor | G3 note: project tree UI (M1.5) | diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index e471f81..6809859 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -1,6 +1,6 @@ # Target-app parity -> **Status:** M1 in progress (text buffer, VFS, engine workspace, project tree, tabs and a plain-text editor in the app), no PHP feature ships · **Last updated:** 2026-10-15 · **Target:** PhpStorm 2026.x +> **Status:** M1 in progress (text buffer, VFS, engine workspace, project tree, tabs and a plain-text editor in the app), no PHP feature ships · **Last updated:** 2026-10-16 · **Target:** PhpStorm 2026.x ## How this is measured @@ -31,7 +31,7 @@ Hours are the estimated agent wall-clock hours for one agent to reach behaviour | HTTP client | 1 | 0% | everything | ~60 (est.) | — | | Web languages | 2 | 0% | everything | ~200 (est.) | — | | Docker and remote | 1 | 0% | everything | ~120 (est.) | — | -| Settings, keymaps, themes | 1 | 0% | settings UI, keymaps, theme switching (theme tokens exist in `lutra_engine::theme`) | ~60 (est.) | — | +| Settings, keymaps, themes | 1 | 2% (est.) | settings UI, keymaps, theme switching (theme tokens exist in `lutra_engine::theme`; M1.9a: settings backend with 3 keys, persistence, `settings.*` commands, no UI yet) | ~60 (est.) | — | | Plug-ins | 0.5 | 0% | everything | ~120 (est.) | — | | AI features | 0.5 | 0% | everything | ~60 (est.) | — | @@ -61,6 +61,7 @@ The project tree is the first user-visible feature (Project view 8%, estimated); | Date | Change | Summary | |---|---|---| +| 2026-10-16 | minor | M1.9a: Settings row 0% → 2% (est.), settings backend without UI | | 2026-10-15 | minor | Calibration note after cycle C1 (factor 0.07) | | 2026-10-15 | minor | Editor core 0% → 8% (estimated): tabs and editor in the app (M1.6) | | 2026-10-15 | minor | Project view 0% → 8% (estimated): tree runs against the engine in the app (M1.4) |