Host: 256 feature flags, the onboarding mode (mode_get/mode_set, shell-only), and the one-time move of replaced plugin files to feature flags

- settings: MAX_FEATURES 64 -> 256 (an older app's whole-map backup still validates)
- modes: ModeState {mode, onboarded, existing} in modes.json; existing is decided natively on the first start
- plugins::migrate: PluginHost.superseded (file -> flag); enabled and as shipped -> flag on and the file goes; edited -> kept, flag left off; marker written last, every step repeatable; map_backup for imported enabled lists
- a superseded file is never written again by install_bundled
- create-waybetter: the host command list and PluginHost.superseded
This commit is contained in:
CRTkafa 2026-09-30 18:34:13 +07:00
parent f31b00eec7
commit 365f55f604
9 changed files with 477 additions and 6 deletions

View file

@ -0,0 +1,316 @@
//! One-time move of first-party plugin files to feature flags.
//!
//! When an app turns a bundled plugin into a feature of an area plugin (its code now runs from the
//! app's feature registry behind a flag), the old file must not keep running next to it, and the
//! owner must not lose what they had on. The app lists the files it replaced ([`Superseded`]:
//! file -> flag) in its [`super::PluginHost`]; [`PluginStore::migrate_superseded`] runs once per
//! listed file, at startup, and leaves the owner's effective state exactly as it was:
//!
//! | The old file is ... | Result |
//! |--------------------------------------------------------|------------------------------------------------------|
//! | enabled, as shipped (never edited) | its flag is turned on; the file and its entry go |
//! | disabled, as shipped | the flag stays off; the file goes |
//! | edited by the owner (or a file of their own) | kept with its on/off state; the flag is left off |
//! | deleted earlier by the owner | nothing; the flag stays off |
//! | not there at all (a fresh install) | nothing |
//!
//! "As shipped" means byte-identical to what the app last wrote (`bundled.json`). The marker
//! (`migrations.json` in the plugins folder) is written last, so a crash in between repeats the
//! steps, and every step is safe to repeat: flags are only ever turned on, and a file already
//! removed is simply not there. The same table maps the `enabled` list of an imported backup
//! ([`map_backup`]).
use super::{content_hash, valid_file_name, PluginStore, BUNDLED_FILE, STATE_FILE};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};
use std::fs;
/// Which superseded files were handled already (in the plugins folder).
pub const MARKER_FILE: &str = "migrations.json";
/// An old first-party plugin file and the feature flag that replaces it.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Superseded {
pub file: &'static str,
pub flag: &'static str,
}
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
struct Marker {
superseded: BTreeSet<String>,
}
/// What one run did (empty when there was nothing left to do).
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Outcome {
/// Flags turned on: their old plugin was enabled and as shipped.
pub flags_on: Vec<String>,
/// Files removed (as shipped).
pub removed: Vec<String>,
/// Files kept because the owner changed them; their replacement flag was left alone.
pub kept: Vec<String>,
}
impl PluginStore {
/// Handles every file of `table` that was not handled before. `turn_on` persists the flags to
/// turn on (it must only ever set them to true and keep every other flag) and runs before any
/// file is touched: when it fails nothing has changed and the next start tries again.
pub fn migrate_superseded(&self, table: &[Superseded], turn_on: impl FnOnce(&[String]) -> Result<(), String>) -> Result<Outcome, String> {
let marker_path = self.dir.join(MARKER_FILE);
let mut marker: Marker = fs::read_to_string(&marker_path).ok().and_then(|raw| serde_json::from_str(&raw).ok()).unwrap_or_default();
let pending: Vec<&Superseded> = table.iter().filter(|row| valid_file_name(row.file) && !marker.superseded.contains(row.file)).collect();
if pending.is_empty() {
return Ok(Outcome::default());
}
fs::create_dir_all(&self.dir).map_err(|error| format!("PLUGINS: {error}"))?;
let manifest_path = self.dir.join(BUNDLED_FILE);
let mut manifest: BTreeMap<String, String> = fs::read_to_string(&manifest_path).ok().and_then(|raw| serde_json::from_str(&raw).ok()).unwrap_or_default();
let mut enabled = self.enabled_set();
let mut outcome = Outcome::default();
let mut gone: Vec<&str> = Vec::new();
for row in &pending {
match fs::read(self.dir.join(row.file)) {
// Deleted earlier (or never installed): nothing to move; a stale enabled entry goes.
Err(_) => gone.push(row.file),
Ok(bytes) => {
if manifest.get(row.file).is_some_and(|installed| *installed == content_hash(&bytes)) {
if enabled.contains(row.file) {
outcome.flags_on.push(row.flag.to_owned());
}
outcome.removed.push(row.file.to_owned());
} else {
outcome.kept.push(row.file.to_owned());
}
}
}
}
turn_on(&outcome.flags_on)?;
let before = enabled.len();
for file in outcome.removed.iter().map(String::as_str).chain(gone.iter().copied()) {
enabled.remove(file);
}
if enabled.len() != before {
let json = serde_json::to_string_pretty(&enabled).map_err(|_| "PLUGINS: serialization failed")?;
fs::write(self.dir.join(STATE_FILE), json).map_err(|error| format!("PLUGINS: {error}"))?;
}
for file in &outcome.removed {
match fs::remove_file(self.dir.join(file)) {
Ok(()) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => return Err(format!("PLUGINS: {error}")),
}
}
// The app no longer ships these files: their "last written" entries go with them. A kept
// (edited) file is an ordinary plugin of the owner's from here on.
let entries = manifest.len();
for row in &pending {
manifest.remove(row.file);
}
if manifest.len() != entries {
let json = serde_json::to_string_pretty(&manifest).map_err(|_| "PLUGINS: serialization failed")?;
fs::write(&manifest_path, json).map_err(|error| format!("PLUGINS: {error}"))?;
}
marker.superseded.extend(pending.iter().map(|row| row.file.to_owned()));
let json = serde_json::to_string_pretty(&marker).map_err(|_| "PLUGINS: serialization failed")?;
fs::write(&marker_path, json).map_err(|error| format!("PLUGINS: {error}"))?;
Ok(outcome)
}
}
/// The `enabled` list of an imported backup, mapped through `table`: a superseded file that the
/// backup only names (it was as shipped, so the backup carries no copy) becomes its flag and leaves
/// the list; one the backup carries a copy of (`files`: the owner's edited version) stays a plugin.
/// Returns the list to enable and the flags to turn on.
pub fn map_backup(enabled: Vec<String>, files: &[String], table: &[Superseded]) -> (Vec<String>, Vec<String>) {
let mut keep = Vec::with_capacity(enabled.len());
let mut flags_on = Vec::new();
for name in enabled {
match table.iter().find(|row| row.file == name) {
Some(row) if !files.contains(&name) => {
if !flags_on.iter().any(|flag| flag == row.flag) {
flags_on.push(row.flag.to_owned());
}
}
_ => keep.push(name),
}
}
(keep, flags_on)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::plugins::PluginHost;
use std::cell::RefCell;
use std::path::Path;
static HOST: PluginHost = PluginHost {
runtime_global: "Demo",
origin: "https://site.test",
product: "wayBetter for Test",
css_element_id: "demo-css",
example: None,
bundled: &[("wb-stays.plugin.js", "stays v1")],
superseded: TABLE,
};
/// The previous version of the app: it still shipped the files.
static OLD_HOST: PluginHost = PluginHost { superseded: &[], ..HOST };
const TABLE: &[Superseded] = &[
Superseded { file: "wb-focus.plugin.js", flag: "navigation.focusMode" },
Superseded { file: "wb-keys.plugin.js", flag: "navigation.keyboardPlus" },
Superseded { file: "wb-edited.plugin.js", flag: "navigation.edited" },
Superseded { file: "wb-deleted.plugin.js", flag: "navigation.deleted" },
];
/// What the previous version shipped.
const OLD: &[(&str, &str)] = &[
("wb-stays.plugin.js", "stays v1"),
("wb-focus.plugin.js", "focus v1"),
("wb-keys.plugin.js", "keys v1"),
("wb-edited.plugin.js", "edited v1"),
("wb-deleted.plugin.js", "deleted v1"),
];
/// A plugins folder as the previous version left it: Focus and the edited one enabled, Keys off.
fn upgraded() -> (tempfile::TempDir, PluginStore) {
let root = tempfile::tempdir().unwrap();
let old = PluginStore::new(root.path().join("plugins"), &OLD_HOST);
fs::create_dir_all(old.dir()).unwrap();
old.install_bundled(OLD);
let store = PluginStore::new(root.path().join("plugins"), &HOST);
fs::write(store.dir().join("wb-edited.plugin.js"), "my own version").unwrap();
fs::remove_file(store.dir().join("wb-deleted.plugin.js")).unwrap();
fs::write(store.dir().join("mine.plugin.js"), "mine").unwrap();
for file in ["wb-focus.plugin.js", "wb-edited.plugin.js", "mine.plugin.js", "wb-stays.plugin.js"] {
store.set_enabled(file, true).unwrap();
}
(root, store)
}
fn exists(store: &PluginStore, file: &str) -> bool {
store.dir().join(file).exists()
}
fn marker(dir: &Path) -> Vec<String> {
let marker: Marker = serde_json::from_str(&fs::read_to_string(dir.join(MARKER_FILE)).unwrap()).unwrap();
marker.superseded.into_iter().collect()
}
#[test]
fn every_case_keeps_the_owners_effective_state() {
let (_root, store) = upgraded();
let turned_on = RefCell::new(Vec::new());
let outcome = store.migrate_superseded(TABLE, |flags| { turned_on.borrow_mut().extend(flags.to_vec()); Ok(()) }).unwrap();
// Enabled and as shipped: the flag takes over and the file goes.
assert_eq!(outcome.flags_on, ["navigation.focusMode"]);
assert_eq!(*turned_on.borrow(), ["navigation.focusMode"]);
assert!(!exists(&store, "wb-focus.plugin.js") && !store.is_enabled("wb-focus.plugin.js"));
// Disabled and as shipped: the file goes, its flag stays off.
assert!(!exists(&store, "wb-keys.plugin.js"));
assert_eq!(outcome.removed, ["wb-focus.plugin.js", "wb-keys.plugin.js"]);
// Edited by the owner: kept, still enabled, and the built-in replacement is left off.
assert_eq!(outcome.kept, ["wb-edited.plugin.js"]);
assert_eq!(fs::read_to_string(store.dir().join("wb-edited.plugin.js")).unwrap(), "my own version");
assert!(store.is_enabled("wb-edited.plugin.js"));
// Deleted earlier: still deleted, flag untouched.
assert!(!exists(&store, "wb-deleted.plugin.js"));
// Everything else is as it was.
assert!(store.is_enabled("mine.plugin.js") && store.is_enabled("wb-stays.plugin.js"));
assert_eq!(fs::read_to_string(store.dir().join("wb-stays.plugin.js")).unwrap(), "stays v1");
assert_eq!(marker(store.dir()), ["wb-deleted.plugin.js", "wb-edited.plugin.js", "wb-focus.plugin.js", "wb-keys.plugin.js"]);
// Nothing runs twice: no old file is enabled while its flag is on.
for row in TABLE {
assert!(!(store.is_enabled(row.file) && outcome.flags_on.iter().any(|flag| flag == row.flag)), "{}", row.file);
}
// The removed files are gone from what the app "last wrote"; the next start does not bring them back.
store.ensure().unwrap();
assert!(!exists(&store, "wb-focus.plugin.js") && !exists(&store, "wb-keys.plugin.js"));
let manifest: BTreeMap<String, String> = serde_json::from_str(&fs::read_to_string(store.dir().join(BUNDLED_FILE)).unwrap()).unwrap();
assert_eq!(manifest.keys().collect::<Vec<_>>(), ["wb-stays.plugin.js"]);
// Even an app that still lists a superseded file as bundled never writes it again.
store.install_bundled(OLD);
assert!(!exists(&store, "wb-focus.plugin.js") && !exists(&store, "wb-deleted.plugin.js"));
}
#[test]
fn it_runs_once_and_later_rows_are_handled_when_they_appear() {
let (_root, store) = upgraded();
let first = &TABLE[..1];
let outcome = store.migrate_superseded(first, |_| Ok(())).unwrap();
assert_eq!(outcome.flags_on, ["navigation.focusMode"]);
assert!(exists(&store, "wb-keys.plugin.js"), "a file the table does not list yet is left alone");
// Again: nothing to do, and the closure is not asked for anything.
let again = store.migrate_superseded(first, |_| panic!("already done")).unwrap();
assert_eq!(again, Outcome::default());
// The owner later drops a file of that name in: it is theirs now, not migrated again.
fs::write(store.dir().join("wb-focus.plugin.js"), "mine now").unwrap();
store.set_enabled("wb-focus.plugin.js", true).unwrap();
// A later version supersedes more files: only the new rows are handled.
let later = store.migrate_superseded(TABLE, |flags| { assert!(flags.is_empty()); Ok(()) }).unwrap();
assert_eq!(later.removed, ["wb-keys.plugin.js"]);
assert!(store.is_enabled("wb-focus.plugin.js") && exists(&store, "wb-focus.plugin.js"));
}
#[test]
fn a_failure_or_crash_between_steps_is_repeated_safely() {
// The flags could not be saved: nothing changed, and the next start tries again.
let (_root, store) = upgraded();
assert!(store.migrate_superseded(TABLE, |_| Err("DISK: full".into())).is_err());
assert!(exists(&store, "wb-focus.plugin.js") && store.is_enabled("wb-focus.plugin.js"));
assert!(!store.dir().join(MARKER_FILE).exists());
let retry = store.migrate_superseded(TABLE, |_| Ok(())).unwrap();
assert_eq!(retry.flags_on, ["navigation.focusMode"]);
// A crash after the flags were saved and the enabled list rewritten, before the files went
// and the marker was written: the flag is already on (saved), so the rerun only cleans up.
let (_root, store) = upgraded();
let enabled: BTreeSet<&str> = ["wb-edited.plugin.js", "mine.plugin.js", "wb-stays.plugin.js"].into();
fs::write(store.dir().join(STATE_FILE), serde_json::to_string(&enabled).unwrap()).unwrap();
let rerun = store.migrate_superseded(TABLE, |flags| { assert!(flags.is_empty(), "flags are only ever turned on, never off"); Ok(()) }).unwrap();
assert_eq!(rerun.removed, ["wb-focus.plugin.js", "wb-keys.plugin.js"]);
assert!(!exists(&store, "wb-focus.plugin.js"));
// A crash after the files went, before the marker: the rerun finds nothing and writes it.
let (_root, store) = upgraded();
store.migrate_superseded(TABLE, |_| Ok(())).unwrap();
fs::remove_file(store.dir().join(MARKER_FILE)).unwrap();
let rerun = store.migrate_superseded(TABLE, |flags| { assert!(flags.is_empty()); Ok(()) }).unwrap();
assert_eq!((rerun.removed.len(), rerun.kept), (0, vec!["wb-edited.plugin.js".to_owned()]));
assert!(store.is_enabled("wb-edited.plugin.js"));
assert_eq!(marker(store.dir()).len(), 4);
}
#[test]
fn a_fresh_install_has_nothing_to_move() {
let root = tempfile::tempdir().unwrap();
let store = PluginStore::new(root.path().join("plugins"), &HOST);
store.ensure().unwrap();
let outcome = store.migrate_superseded(TABLE, |flags| { assert!(flags.is_empty()); Ok(()) }).unwrap();
assert_eq!(outcome, Outcome::default());
assert_eq!(marker(store.dir()).len(), 4);
let listed: Vec<String> = store.list().unwrap().into_iter().map(|plugin| plugin.file).collect();
assert_eq!(listed, ["wb-stays.plugin.js"], "only what the app ships now");
assert!(store.start_scripts().is_empty(), "plugin files stay off until the owner turns them on");
}
#[test]
fn a_stale_enabled_entry_of_a_deleted_file_goes() {
let (_root, store) = upgraded();
let enabled: BTreeSet<&str> = ["wb-deleted.plugin.js", "mine.plugin.js"].into();
fs::write(store.dir().join(STATE_FILE), serde_json::to_string(&enabled).unwrap()).unwrap();
let outcome = store.migrate_superseded(TABLE, |_| Ok(())).unwrap();
assert!(outcome.flags_on.is_empty(), "a file the owner deleted does not turn its flag on");
assert!(!store.is_enabled("wb-deleted.plugin.js") && store.is_enabled("mine.plugin.js"));
}
#[test]
fn a_backup_with_old_names_turns_into_flags_unless_it_carries_an_edited_copy() {
let enabled = vec!["wb-focus.plugin.js".to_owned(), "mine.plugin.js".to_owned(), "wb-edited.plugin.js".to_owned(), "wb-focus.plugin.js".to_owned()];
let files = vec!["mine.plugin.js".to_owned(), "wb-edited.plugin.js".to_owned()];
let (keep, flags_on) = map_backup(enabled, &files, TABLE);
assert_eq!(keep, ["mine.plugin.js", "wb-edited.plugin.js"]);
assert_eq!(flags_on, ["navigation.focusMode"]);
let (keep, flags_on) = map_backup(vec!["other.plugin.js".into()], &[], TABLE);
assert_eq!((keep.len(), flags_on.len()), (1, 0));
}
}