H6: isolated data directory for dev and live-check instances

`--data-dir DIR` / `LUTRA_DATA_DIR` move settings, the recovery journal,
the rendezvous file and the WebView2 user data folder into one directory.
`--control PORT` without either uses `<temp>/lutra-control/<port>/`. The
SHA-256-checked Phpactor cache stays shared from the user's data dir
(`Engine::share_tools_from`). An isolated instance never forwards to or
registers as the user's main instance; `rendezvous::dir()` honours
`LUTRA_DATA_DIR` after `LUTRA_RENDEZVOUS_DIR`, so the CLI finds it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 13:03:31 +01:00
parent e5891ddeb4
commit ba70b0f43a
10 changed files with 418 additions and 29 deletions

View file

@ -8,6 +8,8 @@ use std::path::PathBuf;
pub struct Args {
/// Port for the JSON control channel (`--control PORT`).
pub control: Option<u16>,
/// Isolated data directory (`--data-dir PATH`), see [`crate::datadir`].
pub data_dir: Option<PathBuf>,
/// Folder or file to open.
pub path: Option<PathBuf>,
/// `--help` was given.
@ -17,9 +19,13 @@ pub struct Args {
}
/// Usage text for `--help`.
pub const USAGE: &str = "usage: lutra-desktop [--control PORT] [PATH]
pub const USAGE: &str = "usage: lutra-desktop [--control PORT] [--data-dir DIR] [PATH]
--control PORT serve the JSON control channel on 127.0.0.1:PORT
--control PORT serve the JSON control channel on 127.0.0.1:PORT; without
--data-dir or LUTRA_DATA_DIR the data lives in
<temp>/lutra-control/PORT
--data-dir DIR keep settings, the recovery journal and webview data in
DIR instead of the user's data (also: LUTRA_DATA_DIR)
--version print the version
--help print this help";
@ -41,8 +47,8 @@ pub fn parse_os(args: impl IntoIterator<Item = OsString>) -> Result<Args, String
/// Parses the arguments after the program name.
///
/// # Errors
/// A message for an unknown flag, a missing or invalid port, or more than one
/// path.
/// A message for an unknown flag, a missing or invalid port, a missing or
/// empty data directory, or more than one path.
pub fn parse(args: impl IntoIterator<Item = String>) -> Result<Args, String> {
let mut parsed = Args::default();
let mut args = args.into_iter();
@ -51,11 +57,19 @@ pub fn parse(args: impl IntoIterator<Item = String>) -> Result<Args, String> {
parsed.control = Some(port(value)?);
continue;
}
if let Some(value) = arg.strip_prefix("--data-dir=") {
parsed.data_dir = Some(data_dir(value)?);
continue;
}
match arg.as_str() {
"--control" => {
let value = args.next().ok_or("--control needs a port")?;
parsed.control = Some(port(&value)?);
}
"--data-dir" => {
let value = args.next().ok_or("--data-dir needs a directory")?;
parsed.data_dir = Some(data_dir(&value)?);
}
"--help" | "-h" => parsed.help = true,
"--version" | "-V" => parsed.version = true,
flag if flag.starts_with('-') => return Err(format!("unknown option {flag}")),
@ -81,6 +95,17 @@ fn port(value: &str) -> Result<u16, String> {
}
}
/// Parses a `--data-dir` value.
///
/// # Errors
/// A message if the value is empty.
fn data_dir(value: &str) -> Result<PathBuf, String> {
if value.is_empty() {
return Err("--data-dir needs a directory".into());
}
Ok(PathBuf::from(value))
}
#[cfg(test)]
mod tests {
use super::*;
@ -98,6 +123,17 @@ mod tests {
assert_eq!(p(&[]).unwrap(), Args::default());
}
#[test]
fn parses_data_dir() {
let a = p(&["--control", "7956", "--data-dir", "/tmp/iso", "x"]).unwrap();
assert_eq!(a.data_dir, Some(PathBuf::from("/tmp/iso")));
assert_eq!(a.path, Some(PathBuf::from("x")));
let b = p(&["--data-dir=/tmp/other"]).unwrap();
assert_eq!(b.data_dir, Some(PathBuf::from("/tmp/other")));
assert!(p(&["--data-dir"]).is_err());
assert!(p(&["--data-dir="]).is_err());
}
#[test]
fn rejects_bad_input() {
assert!(p(&["--control"]).is_err());

View file

@ -0,0 +1,232 @@
//! Where a desktop instance keeps its files.
//!
//! A normal start uses the user's data: Tauri's app config and app data
//! directories and the default WebView2 user data folder. An isolated
//! start keeps all of it in one directory instead: `settings.json`, the
//! recovery journal under `recovery/`, the rendezvous file and the
//! webview's own data under [`WEBVIEW_DIR`] (its local storage, so the
//! frontend's remembered state such as recent projects and window layout
//! is separate too). A start is isolated, in this order, when
//! - `--data-dir PATH` is given;
//! - `LUTRA_DATA_DIR` is set and not empty;
//! - `--control PORT` is given: the directory is
//! `<temp>/lutra-control/<port>/`, kept between runs so repeated checks
//! keep their state.
//!
//! This keeps development and live-check instances away from the user's
//! own settings and journal. The managed tools (the SHA-256-checked
//! Phpactor PHAR) stay shared from the user's data directory, so an
//! isolated instance does not download its own copy (see
//! [`lutra_engine::Engine::share_tools_from`]). An isolated instance never
//! forwards to, or registers as, the user's main instance (see
//! [`crate::instance`]).
use std::ffi::OsString;
use std::path::{Path, PathBuf};
use lutra_control::rendezvous;
use lutra_engine::EngineConfig;
use crate::args::Args;
/// Folder for the webview's own data inside an isolated directory.
pub const WEBVIEW_DIR: &str = "webview";
/// Folder under the system temp directory for `--control` instances
/// without an explicit data directory.
pub const CONTROL_TEMP_DIR: &str = "lutra-control";
/// The isolated data directory of this start from its arguments,
/// `LUTRA_DATA_DIR` and the system temp directory; `None` for a normal
/// start that uses the user's data.
pub fn isolated(args: &Args) -> Option<PathBuf> {
isolated_dir(
args,
std::env::var_os(rendezvous::DATA_DIR_ENV),
&std::env::temp_dir(),
)
}
/// The isolated data directory for `args`, given the value of
/// `LUTRA_DATA_DIR` (`env`) and the temp directory (`temp`); see the
/// module docs for the order. A relative directory is made absolute
/// against the current directory, so it does not move if the app changes
/// its working directory.
pub fn isolated_dir(args: &Args, env: Option<OsString>, temp: &Path) -> Option<PathBuf> {
let dir = args
.data_dir
.clone()
.or_else(|| env.filter(|v| !v.is_empty()).map(PathBuf::from))
.or_else(|| {
args.control
.map(|port| temp.join(CONTROL_TEMP_DIR).join(port.to_string()))
})?;
Some(std::path::absolute(&dir).unwrap_or(dir))
}
/// The engine directories of an isolated instance: settings and the
/// journal both live in `dir`.
pub fn engine_config(dir: &Path) -> EngineConfig {
EngineConfig {
config_dir: dir.to_path_buf(),
data_dir: dir.to_path_buf(),
}
}
/// The webview's data folder inside an isolated directory.
pub fn webview_dir(dir: &Path) -> PathBuf {
dir.join(WEBVIEW_DIR)
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use std::time::Duration;
use lutra_control::client::Client;
use lutra_engine::Engine;
use serde_json::{Value, json};
use super::*;
use crate::host::Host;
use crate::instance;
fn control(port: u16) -> Args {
Args {
control: Some(port),
..Args::default()
}
}
#[test]
fn picks_the_flag_then_the_env_then_the_control_temp_dir() {
let tmp = tempfile::tempdir().unwrap();
let temp = tmp.path();
assert_eq!(isolated_dir(&Args::default(), None, temp), None);
assert_eq!(
isolated_dir(&Args::default(), Some(OsString::new()), temp),
None
);
assert_eq!(
isolated_dir(&control(7956), None, temp),
Some(temp.join("lutra-control").join("7956"))
);
let env = temp.join("env");
assert_eq!(
isolated_dir(&control(7956), Some(env.clone().into()), temp),
Some(env.clone())
);
let flag = Args {
data_dir: Some(temp.join("flag")),
..control(7956)
};
assert_eq!(
isolated_dir(&flag, Some(env.into()), temp),
Some(temp.join("flag"))
);
let relative = Args {
data_dir: Some(PathBuf::from("rel")),
..Args::default()
};
let resolved = isolated_dir(&relative, None, temp).unwrap();
assert!(resolved.is_absolute());
assert!(resolved.ends_with("rel"));
}
/// Lists every file under `dir`, relative to it.
fn files(dir: &Path) -> Vec<PathBuf> {
let mut out = Vec::new();
let mut stack = vec![dir.to_path_buf()];
while let Some(d) = stack.pop() {
let Ok(listing) = std::fs::read_dir(&d) else {
continue;
};
for entry in listing {
let path = entry.unwrap().path();
if path.is_dir() {
stack.push(path);
} else {
out.push(path.strip_prefix(dir).unwrap().to_path_buf());
}
}
}
out.sort();
out
}
#[test]
fn a_control_instance_leaves_the_user_data_dir_untouched() {
let tmp = tempfile::tempdir().unwrap();
let user = tmp.path().join("user-data");
std::fs::create_dir_all(&user).unwrap();
std::fs::write(
user.join("settings.json"),
"{\"appearance.theme\":\"lutra-light\"}",
)
.unwrap();
let before = files(&user);
let project = tmp.path().join("project");
std::fs::create_dir_all(&project).unwrap();
std::fs::write(project.join("a.php"), "<?php\n").unwrap();
let args = control(7956);
let dir = isolated_dir(&args, None, &tmp.path().join("temp")).unwrap();
assert!(!dir.starts_with(&user));
if std::env::var_os(rendezvous::DIR_ENV).is_none() {
assert_eq!(instance::rendezvous_dir(&args, Some(&dir)), None);
}
assert!(!webview_dir(&dir).starts_with(&user));
let mut engine = Engine::with_config(engine_config(&dir)).unwrap();
engine.share_tools_from(user.clone());
engine.take_events();
engine
.execute("project.open", json!({"path": project}))
.unwrap();
let id = engine
.execute("file.open", json!({"path": "a.php"}))
.unwrap()
.value["id"]
.as_u64()
.unwrap();
let version = engine
.execute("buffer.get", json!({"id": id}))
.unwrap()
.value["version"]
.clone();
engine
.execute(
"buffer.edit",
json!({"id": id, "baseVersion": version,
"edits": [{"from": 6, "to": 6, "insert": "echo 1;\n"}]}),
)
.unwrap();
engine.flush_journal().unwrap();
let host: Arc<Host> = Host::new(engine);
let server = lutra_control::start(0, host.clone()).unwrap();
let mut client =
Client::connect(server.local_addr().port(), Duration::from_secs(5)).unwrap();
client
.execute(
"settings.set",
json!({"key": "appearance.theme", "value": "lutra-dark"}),
)
.unwrap();
assert_eq!(files(&user), before, "user data dir changed");
assert_eq!(
std::fs::read_to_string(user.join("settings.json")).unwrap(),
"{\"appearance.theme\":\"lutra-light\"}"
);
let stored: Value =
serde_json::from_str(&std::fs::read_to_string(dir.join("settings.json")).unwrap())
.unwrap();
assert_eq!(stored["appearance.theme"], "lutra-dark");
assert!(
files(&dir).iter().any(|f| f.starts_with("recovery")),
"journal in the isolated dir: {:?}",
files(&dir)
);
}
}

View file

@ -10,7 +10,10 @@
//!
//! A start with `--control PORT` is a development or automation instance:
//! it skips all of this, so several of them can run side by side, unless
//! `LUTRA_RENDEZVOUS_DIR` names a rendezvous directory for it.
//! `LUTRA_RENDEZVOUS_DIR` names a rendezvous directory for it. A start with
//! an isolated data directory (`--data-dir`, `LUTRA_DATA_DIR`, see
//! [`crate::datadir`]) keeps its rendezvous file there, so it never
//! forwards to, or registers as, the user's main instance.
use std::path::{Path, PathBuf};
use std::sync::Arc;
@ -25,14 +28,21 @@ use crate::host::Host;
/// How long a second start waits for the running instance to answer.
const PROBE_TIMEOUT: Duration = Duration::from_secs(5);
/// The rendezvous directory this start uses, `None` if it does not take
/// part in the single instance (see the module docs).
pub fn rendezvous_dir(args: &Args) -> Option<PathBuf> {
/// The rendezvous directory this start uses, given its isolated data
/// directory (`isolated`); `None` if it does not take part in the single
/// instance (see the module docs).
pub fn rendezvous_dir(args: &Args, isolated: Option<&Path>) -> Option<PathBuf> {
let explicit = std::env::var_os(rendezvous::DIR_ENV).is_some_and(|v| !v.is_empty());
if args.control.is_some() && !explicit {
if explicit {
return rendezvous::dir();
}
if args.control.is_some() {
return None;
}
rendezvous::dir()
match isolated {
Some(dir) => Some(dir.to_path_buf()),
None => rendezvous::dir(),
}
}
/// Forwards `path` to a running instance found through `dir`.
@ -116,8 +126,22 @@ mod tests {
control: Some(7937),
..Args::default()
};
assert_eq!(rendezvous_dir(&dev), None);
assert_eq!(rendezvous_dir(&Args::default()), rendezvous::dir());
assert_eq!(rendezvous_dir(&dev, None), None);
assert_eq!(rendezvous_dir(&dev, Some(Path::new("/iso"))), None);
if std::env::var_os(rendezvous::DATA_DIR_ENV).is_none() {
assert_eq!(rendezvous_dir(&Args::default(), None), rendezvous::dir());
}
}
#[test]
fn an_isolated_start_meets_only_its_own_instances() {
if std::env::var_os(rendezvous::DIR_ENV).is_some() {
return;
}
let iso = Path::new("/iso");
let dir = rendezvous_dir(&Args::default(), Some(iso));
assert_eq!(dir.as_deref(), Some(iso));
assert_ne!(dir, rendezvous::default_data_dir());
}
#[test]

View file

@ -6,11 +6,14 @@
//! (see [`host`]), opens the project given on the command line, and
//! optionally serves the JSON control channel (`--control PORT`). A normal
//! start is a single instance (see [`instance`]): a second start forwards
//! its path to the running app and exits.
//! its path to the running app and exits. A start with `--data-dir`,
//! `LUTRA_DATA_DIR` or `--control` keeps its files away from the user's
//! (see [`datadir`]).
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
mod args;
mod datadir;
mod host;
mod instance;
mod screenshot;
@ -53,18 +56,27 @@ fn main() -> ExitCode {
}
/// Forwards to a running instance if there is one; otherwise builds the
/// Tauri app, starts the engine with the app's config and data directories,
/// Tauri app, starts the engine with the app's config and data directories
/// (or the isolated data directory, sharing the user's managed tools),
/// the host, the control channel and the single-instance listener, and runs
/// the event loop. The window is created in the setup hook, which runs once
/// the event loop has started. A single-instance listener or rendezvous
/// file that cannot be set up is reported and the app runs without it.
///
/// # Errors
/// A message if a running instance refused the forwarded path, Tauri cannot
/// build the app or resolve its directories, the engine cannot start, or
/// the control port cannot be bound.
/// A message if a running instance refused the forwarded path, the
/// isolated data directory cannot be created, 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 instance_dir = instance::rendezvous_dir(args);
let isolated = datadir::isolated(args);
if let Some(dir) = &isolated {
std::fs::create_dir_all(dir)
.map_err(|e| format!("cannot create the data directory {}: {e}", dir.display()))?;
eprintln!("lutra: data directory {}", dir.display());
}
let webview_dir = isolated.as_deref().map(datadir::webview_dir);
let instance_dir = instance::rendezvous_dir(args, isolated.as_deref());
if let Some(dir) = &instance_dir
&& instance::forward(dir, args.path.as_deref())?
{
@ -90,6 +102,9 @@ fn run(args: &args::Args) -> Result<(), String> {
.inner_size(1200.0, 800.0)
.min_inner_size(640.0, 400.0)
.initialization_script(theme::init_script(&setting));
if let Some(dir) = &webview_dir {
window = window.data_directory(dir.clone());
}
if let Some(color) = token_color(&theme::resolve(&setting, None), "bg") {
window = window.background_color(color);
}
@ -106,7 +121,15 @@ fn run(args: &args::Args) -> Result<(), 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())?;
let user = engine_config(&app)?;
let config = match &isolated {
Some(dir) => datadir::engine_config(dir),
None => user.clone(),
};
let mut engine = Engine::with_config(config).map_err(|e| e.to_string())?;
if isolated.is_some() {
engine.share_tools_from(user.data_dir);
}
engine.allow_downloads().map_err(|e| e.to_string())?;
let startup = engine.take_events();
let host = Host::new(engine);
@ -141,8 +164,9 @@ fn run(args: &args::Args) -> Result<(), String> {
Ok(())
}
/// The engine directories from Tauri's path resolver: the app config dir
/// for settings, the app data dir for the recovery journal.
/// The user's engine directories from Tauri's path resolver: the app config
/// dir for settings, the app data dir for the recovery journal and the
/// managed tools. Resolving creates nothing.
///
/// # Errors
/// A message if the platform has no such directories.

View file

@ -14,7 +14,8 @@
//! that ACL. A file whose listener does not answer, or answers without
//! accepting the token, is stale: the next app start replaces it.
//!
//! The directory is [`dir`]: `LUTRA_RENDEZVOUS_DIR` if set, otherwise
//! The directory is [`dir`]: `LUTRA_RENDEZVOUS_DIR` if set, otherwise the
//! isolated data directory `LUTRA_DATA_DIR` if set, otherwise
//! [`default_data_dir`], which matches Tauri's `app_data_dir()` for the
//! identifier [`APP_IDENTIFIER`].
@ -32,6 +33,13 @@ pub const FILE_NAME: &str = "instance.json";
/// takes part in the single instance only when it is set.
pub const DIR_ENV: &str = "LUTRA_RENDEZVOUS_DIR";
/// Environment variable that moves a desktop instance's whole data
/// directory (settings, recovery journal, rendezvous file, webview data)
/// away from the user's, like the desktop's `--data-dir PATH`. Such an
/// instance is isolated: it never forwards to or registers as the user's
/// main instance. The CLI looks for the rendezvous file there too.
pub const DATA_DIR_ENV: &str = "LUTRA_DATA_DIR";
/// The Tauri app identifier, the last part of the data directory.
pub const APP_IDENTIFIER: &str = "dev.lutra.desktop";
@ -79,12 +87,17 @@ impl std::fmt::Display for ReadError {
impl std::error::Error for ReadError {}
/// The rendezvous directory: `LUTRA_RENDEZVOUS_DIR` if set and not empty,
/// otherwise [`default_data_dir`].
/// otherwise `LUTRA_DATA_DIR` if set and not empty (made absolute against
/// the current directory), otherwise [`default_data_dir`].
pub fn dir() -> Option<PathBuf> {
match std::env::var_os(DIR_ENV) {
Some(value) if !value.is_empty() => Some(PathBuf::from(value)),
_ => default_data_dir(),
}
let set = |name: &str| {
std::env::var_os(name)
.filter(|value| !value.is_empty())
.map(PathBuf::from)
};
set(DIR_ENV)
.or_else(|| set(DATA_DIR_ENV).map(|p| std::path::absolute(&p).unwrap_or(p)))
.or_else(default_data_dir)
}
/// The app data directory as Tauri computes it for [`APP_IDENTIFIER`]:

View file

@ -101,6 +101,10 @@ pub struct Toolchain {
config: Option<Config>,
/// The project root the last job saw.
root: Option<PathBuf>,
/// Where the managed tools live (`tools/phpactor/<version>/`) when that
/// is not the engine's data directory; see
/// [`crate::Engine::share_tools_from`].
tools_dir: Option<PathBuf>,
}
impl Toolchain {
@ -114,6 +118,12 @@ impl Toolchain {
pub fn allow_downloads(&mut self, source: Source) {
self.source = Some(source);
}
/// Keeps the managed tools in `dir` instead of the engine's data
/// directory.
pub fn set_tools_dir(&mut self, dir: PathBuf) {
self.tools_dir = Some(dir);
}
}
/// The settings and directories a job runs with.
@ -125,7 +135,8 @@ struct Config {
phpactor_path: String,
/// `phpactor.autoDownload`.
auto_download: bool,
/// The engine's data directory.
/// The directory holding the managed tools: the toolchain's tools
/// directory if set, else the engine's data directory.
data_dir: Option<PathBuf>,
}
@ -236,7 +247,11 @@ fn config(state: &State) -> Config {
.get("phpactor.autoDownload")
.and_then(|v| v.as_bool())
.unwrap_or(true),
data_dir: state.config.as_ref().map(|c| c.data_dir.clone()),
data_dir: state
.toolchain
.tools_dir
.clone()
.or_else(|| state.config.as_ref().map(|c| c.data_dir.clone())),
}
}
@ -883,4 +898,32 @@ mod tests {
Mode::Auto(PathBuf::from("p"))
);
}
#[test]
fn a_shared_tools_dir_is_used_instead_of_the_data_dir() {
let dir = tempfile::tempdir().unwrap();
let shared = dir.path().join("user-data");
let body = b"shared phar".to_vec();
let path = phpactor::managed_path(&shared, "1.0.0");
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, &body).unwrap();
let mut engine = engine(dir.path());
engine.share_tools_from(shared.clone());
engine.allow_downloads_from(Source {
url: "http://127.0.0.1:9/never".into(),
version: "1.0.0".into(),
sha256: Hash::of_bytes(&body),
https_only: false,
});
engine.execute("toolchain.status", Value::Null).unwrap();
let events = pump_until(&mut engine, |ev| {
last_status(ev).is_some_and(|s| s.phpactor.state == PhpactorState::Ready)
});
let status = last_status(&events).unwrap();
assert_eq!(
status.phpactor.path.as_deref(),
Some(path.display().to_string().as_str())
);
assert!(!dir.path().join("data").join("tools").exists());
}
}

View file

@ -242,6 +242,15 @@ impl Engine {
self.state.toolchain.allow_downloads(source);
}
/// Looks for (and downloads) the managed tools such as the Phpactor
/// PHAR under `dir` instead of the data directory of the engine's
/// [`EngineConfig`]. An isolated desktop instance (`--data-dir`,
/// `--control`) passes the user's normal data directory, so it shares
/// the SHA-256-checked cache instead of downloading its own copy.
pub fn share_tools_from(&mut self, dir: PathBuf) {
self.state.toolchain.set_tools_dir(dir);
}
/// Makes the engine run `launch` as the project's language server
/// instead of Phpactor from the toolchain; `None` goes back to the
/// toolchain. For tests (the fake server) and hosts with their own

View file

@ -71,6 +71,7 @@ As built in M0:
- **Security:** only the user may read the token. Unix: the file is created with mode `0600`. Windows: it lives in the user's roaming AppData folder, whose inherited ACL grants the user, `SYSTEM` and Administrators only (checked with `icacls` in the M3.7 live check); Lutra sets no ACL of its own. Both listeners bind `127.0.0.1` only. On the token listener the first request must be `app.auth {token}` within 10 s (`AUTH_TIMEOUT`); a wrong token, another method or garbage gets `unauthorized` and the connection is closed. Tokens are compared in constant time. The `--control PORT` listener stays open (no token) for development and agents; it is opt-in and documented as such.
- **Second start:** `lutra-desktop [PATH]` without `--control` reads the rendezvous file first. If the listener answers, accepts the token and pings, the start forwards `PATH` (folder → `project.open`, file → `file.open`), calls `app.focus` and exits 0. If the file is missing, unreadable, invalid, or its port refuses or rejects the token, it is stale: this start becomes the instance and replaces the file. Two starts in the same instant can both become instances; the later file wins (accepted, rare).
- **Development instances:** a start with `--control PORT` skips the single instance (no forwarding, no rendezvous file) so parallel agents' instances never forward to each other, unless `LUTRA_RENDEZVOUS_DIR` is set, which opts it into the single instance in that directory (used for isolated live checks).
- **Data directory isolation (H6):** `lutra-desktop --data-dir DIR` or `LUTRA_DATA_DIR=DIR` makes an isolated instance (`apps/lutra-desktop/src/datadir.rs`): `EngineConfig { config_dir: DIR, data_dir: DIR }` (settings, `recovery/`), the rendezvous file in `DIR`, and the webview's own data in `DIR/webview` (`WebviewWindowBuilder::data_directory`, the WebView2 user data folder, so local storage is separate too). `--control PORT` without either uses `<temp>/lutra-control/<port>/`, kept between runs. The managed tools stay shared: `Engine::share_tools_from(user app_data_dir)` makes the toolchain look for (and, only if missing, download) `tools/phpactor/<version>/` there, SHA-256 checked as before. Rendezvous order: `LUTRA_RENDEZVOUS_DIR` if set; else none for `--control`; else the isolated directory; else the default. `rendezvous::dir()` (CLI, `lutra mcp`) honours `LUTRA_DATA_DIR` after `LUTRA_RENDEZVOUS_DIR`, so `lutra` finds an isolated instance started with the same environment. An isolated instance therefore never forwards to, or registers as, the user's main instance.
- **New methods:** `app.auth {token}` (always succeeds on the open listener) and `app.focus` (restore, show and focus the main window; `focus_failed` without a window; `Backend::focus` has a default that fails, so test backends need no change).
- **`lutra` CLI** (`apps/lutra-cli`, binary `lutra`, now L6 so it can use `lutra-control`): `lutra [--wait] [PATH[:LINE[:COLUMN]]]...`.
- **Targets:** up to two trailing `:N` groups are a 1-based line and column (`N` all digits, something before it; on Windows a lone drive letter is never split). If the path part does not exist but the whole argument does, the argument is the path. Paths are made absolute against the current directory without resolving symlinks.
@ -544,6 +545,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-25 | minor | H6: isolated data directory (`--data-dir`, `LUTRA_DATA_DIR`, `--control` temp dir), shared tools dir, rendezvous order |
| 2026-10-22 | minor | M3.5: definition, references, rename (`lsp_nav`, workspace edits, undoable remote edits, nav UI) |
| 2026-10-22 | minor | M3.4: code assistance (`lsp.completion`, `lsp.hover`, `lsp.signatureHelp` on pending outcomes; editor completion source, hover, signature help, safe Markdown, assist UI commands), Phpactor latency and resources |
| 2026-10-22 | minor | M3.5 step 1: pending outcomes (`Pending`, `Engine::resolve`, `run_waiting`), `engine_execute_waiting` / `runWaiting` |

View file

@ -18,6 +18,8 @@ cargo xtask ci # the full quality gate, run before every commit
cargo xtask fixtures # create Symfony and Laravel reference projects in target/fixtures/
```
A `--control PORT` instance keeps its settings, recovery journal and webview data in `<temp>/lutra-control/<port>/`, never in your own data directory; `--data-dir DIR` or `LUTRA_DATA_DIR=DIR` pick another directory. Delete the folder to start fresh.
## Robustness: Lutra never crashes
Shipped code returns errors instead of panicking (see AGENTS.md › Never crash). The engine guard catches panics at every entry point, keeps buffers intact and reports an internal error. Unsaved buffers are journaled so a restart can restore them.
@ -30,5 +32,6 @@ No inline comments. Doc comment blocks above modules, functions, types and field
| Date | Change | Summary |
|---|---|---|
| 2026-10-25 | minor | Isolated data directory for `--control` instances (H6) |
| 2026-10-14 | minor | Node.js 22.12+ required by the frontend toolchain |
| 2026-10-13 | major | Initial draft |

View file

@ -34,6 +34,8 @@ G4 progress: M2.1 added the structural half in `crates/syntax`: tree-sitter PHP
G11 progress: M1.7 added the crash-recovery journal: unsaved buffers are written atomically about 1 s after the last edit and offered back after a crash; corrupt entries are skipped with a warning. Covered by a property test (random edits, crash, restore equals the buffer) and a headless control-channel test; not yet checked by killing the running app (gaming mode). Open: journal writes run under the engine lock (8.5 ms for 1 MiB, release), two instances on one project share a journal, local history.
G11 progress (H6): development and live-check instances no longer share the user's data. `--data-dir PATH` / `LUTRA_DATA_DIR` move settings, the recovery journal, the rendezvous file and the WebView2 user data (local storage) into one directory; `--control PORT` without either uses `<temp>/lutra-control/<port>/`. The Phpactor cache stays shared from the user's data directory. An isolated instance never forwards to or registers as the user's main instance. A unit test drives an isolated `--control` engine through the control channel (`settings.set`, journal write) and checks the user directory is byte-for-byte unchanged.
G14 progress: M1.11 moved every UI string in `ui/src` into the English catalog `ui/src/i18n/en.json` behind `t(key, params?)`, enforced by `vue/no-bare-strings-in-template` and a catalog test. Messages the engine sends (`EngineError.message`, the slogan from `app.about`) are still English text; they need message keys with params before a second language can cover them.
G5 progress: M2.3 landed the find-in-files backend: `crates/search` (parallel walk with the project's ignore rules, literal or regex, case, whole word, globs, binary and size skips, match cap, cancel) and the engine commands `search.find` / `search.cancel` with streamed `searchResults` and `searchDone` events; dirty buffers are searched in their buffer text. First result on a generated 20k-file tree 10–43 ms (release, measured). M2.4 added the Find tool window in a new bottom panel (options, globs, grouped and highlighted results, counts, cancel, truncated hint, keyboard navigation, `editor.reveal`, `find.open` `Mod+Alt+F` with prefill). M2.5 added the first symbol index (`crates/index`: every project file, PHP declarations from tree-sitter outlines, vendor as library, parallel build off the engine lock, incremental on disk and buffer changes, cancelled on project close) and the commands `index.status`, `goto.file`, `goto.class`, `goto.symbol` with `indexProgress`/`indexReady` events; a generated 20k-file project (88 MB of PHP) indexes in 3.9–4.2 s (release, measured, target 5 s), queries take 2–12 ms. M2.6 added the go-to popup (Files / Classes / Symbols tabs, `Mod+P`, `Mod+Alt+C`, `Mod+T`, live fuzzy results with marked characters, library rows labelled, indexing hint, `editor.reveal`). Open in G5: replace in files, scopes and history, go-to extras (recent files on an empty query, a non-project toggle, `:line`, file-type filter), an index that survives restarts, changes in directories the non-recursive watcher does not watch, usages.
@ -50,6 +52,7 @@ G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framin
| Date | Change | Summary |
|---|---|---|
| 2026-10-25 | minor | G11 note: isolated data directory for dev and live-check instances (H6) |
| 2026-10-22 | minor | G6 shrunk: definition, references, rename (M3.5) |
| 2026-10-22 | minor | G6 shrunk: completion, hover and signature help (M3.4) |
| 2026-10-21 | minor | G6 shrunk: engine wiring and diagnostics (M3.3) |