B1: alpha installers (NSIS, DMG), identifier com.tyrveil.lutra with data migration

- App identifier com.tyrveil.lutra (D26) in tauri.conf.json and
  rendezvous::APP_IDENTIFIER; a test keeps them equal.
- First normal start copies settings.json, recovery/ and tools/ once from
  the dev.lutra.desktop directories (staging dir + rename, logged, info
  notification); old directories stay untouched.
- Bundling on: per-user NSIS setup (English, German, Start menu, optional
  desktop shortcut, uninstaller) and DMG; `cargo xtask bundle` builds the
  platform's installer, joining the DMG backgrounds into a HiDPI TIFF on
  macOS. build.rs also writes icons/512x512.png for the .icns.
- Installer images from the banner, designed by Amy, generated by
  `cargo xtask installer-images` (assets/installer/, ASSETS.md rows);
  approved by Daniel.
- docs/install.md (SmartScreen, Gatekeeper, uninstall, data locations),
  README install section, architecture, development and macOS notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-31 21:48:15 +01:00
parent 071b2a5644
commit bd225d9e3a
22 changed files with 1367 additions and 17 deletions

View file

@ -10,7 +10,9 @@
//! `LUTRA_DATA_DIR` or `--control` keeps its files away from the user's
//! (see [`datadir`]). With `--control` the window opens without taking the
//! foreground, so an agent starting Lutra does not catch the user's typing;
//! `app.focus` brings it to the front on request.
//! `app.focus` brings it to the front on request. The first normal start
//! under the current app identifier copies the user's files from the
//! placeholder identifier's directories (see [`migrate`]).
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
@ -19,13 +21,14 @@ mod datadir;
mod host;
mod instance;
mod menu;
mod migrate;
mod screenshot;
use std::process::ExitCode;
use std::sync::{Arc, OnceLock};
use lutra_engine::{CommandInfo, Engine, EngineConfig, ErrorPayload, theme};
use serde_json::Value;
use lutra_engine::{CommandInfo, Engine, EngineConfig, ErrorPayload, NotificationLevel, theme};
use serde_json::{Map, Value, json};
use tauri::window::Color;
use tauri::{Manager, WebviewUrl, WebviewWindowBuilder};
@ -59,7 +62,9 @@ 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, copies the user's files from the placeholder identifier once
/// (normal starts only, see [`migrate`]), 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
@ -129,6 +134,11 @@ fn run(args: &args::Args) -> Result<(), String> {
.build(tauri::generate_context!())
.map_err(|e| e.to_string())?;
let user = engine_config(&app)?;
let migration = if isolated.is_none() {
migrate_legacy(&user)
} else {
None
};
let config = match &isolated {
Some(dir) => datadir::engine_config(dir),
None => user.clone(),
@ -138,7 +148,10 @@ fn run(args: &args::Args) -> Result<(), String> {
engine.share_tools_from(user.data_dir);
}
engine.allow_downloads().map_err(|e| e.to_string())?;
let startup = engine.take_events();
let mut startup = engine.take_events();
if let Some((level, key, message, params)) = migration {
startup.extend(engine.notify(level, Some(key), Some(message), Some(params)));
}
let host = Host::new(engine);
host.publish_startup(&startup);
app.manage(host.clone());
@ -189,6 +202,51 @@ fn engine_config(app: &tauri::App) -> Result<EngineConfig, String> {
})
}
/// A notification about the one-time copy from the placeholder
/// identifier's directories: what [`migrate::migrate`] did, logged to
/// standard error and returned as (level, catalog key, English text,
/// params) for the window. `None` if there was nothing to copy or the old
/// directories cannot be derived.
fn migrate_legacy(
user: &EngineConfig,
) -> Option<(NotificationLevel, &'static str, String, Map<String, Value>)> {
let old = migrate::legacy_dirs(user)?;
match migrate::migrate(&old, user) {
Ok(None) => None,
Ok(Some(migrated)) => {
let summary = migrated.summary();
eprintln!("lutra: {summary}");
let mut params = Map::new();
params.insert("from".into(), json!(migrated.from.display().to_string()));
params.insert("to".into(), json!(migrated.to.display().to_string()));
Some((
NotificationLevel::Info,
"notification.app.dataMigrated",
format!("Lutra {summary}."),
params,
))
}
Err(e) => {
eprintln!(
"lutra: cannot copy the data from {}: {e}",
old.data_dir.display()
);
let mut params = Map::new();
params.insert("from".into(), json!(old.data_dir.display().to_string()));
params.insert("error".into(), json!(e.to_string()));
Some((
NotificationLevel::Warning,
"notification.app.dataMigrationFailed",
format!(
"Cannot copy your settings and tools from {}: {e}. Lutra starts with the defaults and tries again next time.",
old.data_dir.display()
),
params,
))
}
}
}
/// The stored `appearance.theme` value, `system` if it cannot be read.
fn stored_theme(host: &Host) -> String {
host.run(

View file

@ -0,0 +1,309 @@
//! The one-time move from the placeholder app identifier.
//!
//! Until the alpha installers, the app identifier was
//! [`rendezvous::LEGACY_APP_IDENTIFIER`] (`dev.lutra.desktop`); it is now
//! [`rendezvous::APP_IDENTIFIER`] (`com.tyrveil.lutra`). Tauri derives the
//! config and data directories from the identifier, so a normal start would
//! begin with empty directories. On the first normal start under the new
//! identifier, when the new data directory does not exist and an old
//! directory does, [`migrate`] copies the user's files over once:
//! `settings.json` from the config directory, the recovery journal
//! (`recovery/`) and the managed tools (`tools/`, the Phpactor PHAR) from
//! the data directory. The old directories stay as they are, so an older
//! build still finds its files. The rendezvous file is not copied; it
//! belongs to a running instance.
//!
//! The data directory is assembled in a sibling staging directory and
//! renamed into place at the end, so a start that fails half-way leaves no
//! new data directory and the next start tries again. On Windows and macOS
//! the config and data directories are the same folder; on Linux
//! `settings.json` goes straight into the new config directory, never
//! replacing one that is already there.
//!
//! The webview's own data (recent projects, window layout) lives in a
//! folder the webview manages and is not copied.
use std::fs;
use std::io;
use std::path::{Path, PathBuf};
use lutra_control::rendezvous;
use lutra_engine::EngineConfig;
/// Name of the settings file inside the config directory.
const SETTINGS_FILE: &str = "settings.json";
/// Folders copied from the old data directory: the recovery journal and
/// the managed tools.
const DATA_DIRS: [&str; 2] = ["recovery", "tools"];
/// Suffix of the staging directory next to the new data directory.
const STAGING_SUFFIX: &str = ".migrating";
/// What [`migrate`] copied.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Migrated {
/// The old data directory the files came from.
pub from: PathBuf,
/// The new data directory.
pub to: PathBuf,
/// The copied entries, `settings.json`, `recovery` and `tools`, in
/// that order, each only if it existed.
pub entries: Vec<&'static str>,
}
impl Migrated {
/// A one-line English summary for the log and the notification.
pub fn summary(&self) -> String {
format!(
"copied {} from {} to {}",
self.entries.join(", "),
self.from.display(),
self.to.display()
)
}
}
/// The directories the placeholder identifier used, next to `current`'s:
/// each one's last component replaced by
/// [`rendezvous::LEGACY_APP_IDENTIFIER`]. `None` if a directory has no
/// parent.
pub fn legacy_dirs(current: &EngineConfig) -> Option<EngineConfig> {
let legacy = |dir: &Path| Some(dir.parent()?.join(rendezvous::LEGACY_APP_IDENTIFIER));
Some(EngineConfig {
config_dir: legacy(&current.config_dir)?,
data_dir: legacy(&current.data_dir)?,
})
}
/// Copies the user's files from `old` to `new` once; see the module docs.
///
/// # Returns
/// `None` if there was nothing to do: the new data directory exists, or
/// neither old directory does. Otherwise what was copied.
///
/// # Errors
/// If a file cannot be read, copied or the staging directory renamed. The
/// new data directory is then not created, so the next start tries again.
pub fn migrate(old: &EngineConfig, new: &EngineConfig) -> io::Result<Option<Migrated>> {
if new.data_dir.exists() || !(old.data_dir.is_dir() || old.config_dir.is_dir()) {
return Ok(None);
}
let staging = staging_dir(&new.data_dir)?;
if staging.exists() {
fs::remove_dir_all(&staging)?;
}
fs::create_dir_all(&staging)?;
let mut entries = Vec::new();
let settings = old.config_dir.join(SETTINGS_FILE);
if settings.is_file() {
let target_dir = if new.config_dir == new.data_dir {
staging.clone()
} else {
new.config_dir.clone()
};
let target = target_dir.join(SETTINGS_FILE);
if !target.exists() {
fs::create_dir_all(&target_dir)?;
fs::copy(&settings, &target)?;
entries.push(SETTINGS_FILE);
}
}
for name in DATA_DIRS {
let source = old.data_dir.join(name);
if fs::symlink_metadata(&source).is_ok_and(|m| m.is_dir()) {
copy_dir(&source, &staging.join(name))?;
entries.push(name);
}
}
fs::rename(&staging, &new.data_dir)?;
Ok(Some(Migrated {
from: old.data_dir.clone(),
to: new.data_dir.clone(),
entries,
}))
}
/// The staging directory next to `data_dir`: its name plus
/// [`STAGING_SUFFIX`].
///
/// # Errors
/// If `data_dir` has no file name.
fn staging_dir(data_dir: &Path) -> io::Result<PathBuf> {
let name = data_dir
.file_name()
.ok_or_else(|| io::Error::other("the data directory has no name"))?;
let mut staged = name.to_os_string();
staged.push(STAGING_SUFFIX);
Ok(data_dir.with_file_name(staged))
}
/// Copies the directory `from` to `to` with its files and subdirectories.
/// Symbolic links are skipped, so the copy never leaves the old directory.
///
/// # Errors
/// If a directory cannot be listed or created, or a file copied.
fn copy_dir(from: &Path, to: &Path) -> io::Result<()> {
fs::create_dir_all(to)?;
for entry in fs::read_dir(from)? {
let entry = entry?;
let kind = entry.file_type()?;
let target = to.join(entry.file_name());
if kind.is_dir() {
copy_dir(&entry.path(), &target)?;
} else if kind.is_file() {
fs::copy(entry.path(), &target)?;
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
/// Directories as on Windows and macOS: config and data are one folder.
fn shared(base: &Path, id: &str) -> EngineConfig {
EngineConfig {
config_dir: base.join(id),
data_dir: base.join(id),
}
}
/// Fills `dir` like a user's data directory of the old identifier.
fn fill(dir: &EngineConfig) {
fs::create_dir_all(&dir.config_dir).unwrap();
fs::write(
dir.config_dir.join("settings.json"),
"{\"appearance.theme\":\"lutra-light\"}",
)
.unwrap();
let journal = dir.data_dir.join("recovery").join("p1");
fs::create_dir_all(&journal).unwrap();
fs::write(journal.join("e1.json"), "{}").unwrap();
let tools = dir.data_dir.join("tools").join("phpactor").join("2025.1");
fs::create_dir_all(&tools).unwrap();
fs::write(tools.join("phpactor.phar"), "phar").unwrap();
fs::write(dir.data_dir.join("instance.json"), "{}").unwrap();
}
#[test]
fn the_legacy_dirs_sit_next_to_the_current_ones() {
let base = Path::new("/home/u");
let current = EngineConfig {
config_dir: base.join(".config").join(rendezvous::APP_IDENTIFIER),
data_dir: base.join(".local/share").join(rendezvous::APP_IDENTIFIER),
};
let legacy = legacy_dirs(&current).unwrap();
assert_eq!(legacy.config_dir, base.join(".config/dev.lutra.desktop"));
assert_eq!(legacy.data_dir, base.join(".local/share/dev.lutra.desktop"));
}
#[test]
fn copies_settings_journal_and_tools_once() {
let tmp = tempfile::tempdir().unwrap();
let old = shared(tmp.path(), rendezvous::LEGACY_APP_IDENTIFIER);
let new = shared(tmp.path(), rendezvous::APP_IDENTIFIER);
fill(&old);
let migrated = migrate(&old, &new).unwrap().unwrap();
assert_eq!(migrated.entries, ["settings.json", "recovery", "tools"]);
assert_eq!(migrated.to, new.data_dir);
assert!(
migrated
.summary()
.contains("settings.json, recovery, tools")
);
assert_eq!(
fs::read_to_string(new.config_dir.join("settings.json")).unwrap(),
"{\"appearance.theme\":\"lutra-light\"}"
);
assert!(new.data_dir.join("recovery/p1/e1.json").is_file());
assert_eq!(
fs::read(new.data_dir.join("tools/phpactor/2025.1/phpactor.phar")).unwrap(),
b"phar"
);
assert!(!new.data_dir.join("instance.json").exists());
assert!(old.data_dir.join("settings.json").is_file(), "old dir kept");
assert!(!staging_dir(&new.data_dir).unwrap().exists());
fs::write(new.config_dir.join("settings.json"), "{}").unwrap();
assert_eq!(migrate(&old, &new).unwrap(), None);
assert_eq!(
fs::read_to_string(new.config_dir.join("settings.json")).unwrap(),
"{}"
);
}
#[test]
fn does_nothing_without_an_old_dir_or_with_a_new_one() {
let tmp = tempfile::tempdir().unwrap();
let old = shared(tmp.path(), rendezvous::LEGACY_APP_IDENTIFIER);
let new = shared(tmp.path(), rendezvous::APP_IDENTIFIER);
assert_eq!(migrate(&old, &new).unwrap(), None);
assert!(!new.data_dir.exists());
fill(&old);
fs::create_dir_all(&new.data_dir).unwrap();
assert_eq!(migrate(&old, &new).unwrap(), None);
assert!(!new.data_dir.join("settings.json").exists());
}
#[test]
fn copies_only_what_exists() {
let tmp = tempfile::tempdir().unwrap();
let old = shared(tmp.path(), rendezvous::LEGACY_APP_IDENTIFIER);
let new = shared(tmp.path(), rendezvous::APP_IDENTIFIER);
fs::create_dir_all(&old.config_dir).unwrap();
fs::write(old.config_dir.join("settings.json"), "{}").unwrap();
let migrated = migrate(&old, &new).unwrap().unwrap();
assert_eq!(migrated.entries, ["settings.json"]);
assert!(new.data_dir.join("settings.json").is_file());
}
#[test]
fn separate_config_dirs_keep_existing_settings() {
let tmp = tempfile::tempdir().unwrap();
let dirs = |id: &str| EngineConfig {
config_dir: tmp.path().join("config").join(id),
data_dir: tmp.path().join("data").join(id),
};
let old = dirs(rendezvous::LEGACY_APP_IDENTIFIER);
let new = dirs(rendezvous::APP_IDENTIFIER);
fill(&old);
fs::create_dir_all(&new.config_dir).unwrap();
fs::write(new.config_dir.join("settings.json"), "{\"mine\":1}").unwrap();
let migrated = migrate(&old, &new).unwrap().unwrap();
assert_eq!(migrated.entries, ["recovery", "tools"]);
assert_eq!(
fs::read_to_string(new.config_dir.join("settings.json")).unwrap(),
"{\"mine\":1}"
);
assert!(!new.data_dir.join("settings.json").exists());
assert!(new.data_dir.join("recovery/p1/e1.json").is_file());
}
#[test]
fn a_leftover_staging_dir_is_replaced() {
let tmp = tempfile::tempdir().unwrap();
let old = shared(tmp.path(), rendezvous::LEGACY_APP_IDENTIFIER);
let new = shared(tmp.path(), rendezvous::APP_IDENTIFIER);
fill(&old);
let staging = staging_dir(&new.data_dir).unwrap();
fs::create_dir_all(staging.join("recovery")).unwrap();
fs::write(staging.join("half-copied"), "x").unwrap();
migrate(&old, &new).unwrap().unwrap();
assert!(!new.data_dir.join("half-copied").exists());
assert!(!staging.exists());
assert!(new.data_dir.join("recovery/p1/e1.json").is_file());
}
#[test]
fn the_tauri_config_uses_the_app_identifier() {
let conf: serde_json::Value =
serde_json::from_str(include_str!("../tauri.conf.json")).unwrap();
assert_eq!(conf["identifier"], rendezvous::APP_IDENTIFIER);
}
}