Merge pull request #197 from samsoir/feat/152-disable-overlays-config

feat(packages): runtime control to disable XEL overlays (#152)

Author: samsoir

docs/configuration.md

@@ -429,6 +429,7 @@ Controls package manager behavior.
 | `install_location` | path | `~/.xearthlayer/packages` | Directory for storing installed packages |
 | `custom_scenery_path` | path | (auto-detect) | X-Plane Custom Scenery directory for overlay symlinks |
 | `auto_install_overlays` | bool | `false` | Automatically install matching overlay when installing ortho |
+| `disable_overlays` | bool | `false` | Suppress XEL overlays at runtime (see notes below) |
 | `temp_dir` | path | `~/.xearthlayer/tmp` | Temporary directory for package downloads |
 | `concurrent_downloads` | Integer | `5` | Number of concurrent part downloads (1-10) |
 
@@ -439,13 +440,15 @@ Controls package manager behavior.
 install_location = ~/.xearthlayer/packages
 custom_scenery_path = /home/user/X-Plane 12/Custom Scenery
 auto_install_overlays = true
+disable_overlays = false
 temp_dir = ~/Downloads/xearthlayer-temp
 ```
 
 **Notes:**
 - The default `library_url` points to the official XEarthLayer package library; override only if using a custom package source
 - The `temp_dir` is used for downloading archives before extraction; files are cleaned up after installation. The default avoids the system temp directory which is often RAM-backed (tmpfs) on Linux
 - When `auto_install_overlays` is enabled, installing an ortho package will automatically install the matching overlay package for the same region (if available)
+- `disable_overlays` is a **runtime** control. When set to `true`, `xearthlayer run` removes the consolidated `yzXEL_overlay/` symlink folder from Custom Scenery on startup so X-Plane does not load XEarthLayer overlays. Overlay packages remain downloaded and stored locally — flipping the setting back to `false` and restarting reinstates them with no re-download. Use this when running third-party overlay scenery (e.g. SimHeaven, Prefab Objects) that conflicts with XEL overlays. Distinct from `auto_install_overlays`, which controls whether overlays are *downloaded* alongside ortho packages.
 - If `custom_scenery_path` is not set, it falls back to `[xplane] scenery_dir` or auto-detects from X-Plane installation
 
 ---
@@ -569,6 +572,7 @@ file = ~/.xearthlayer/xearthlayer.log
 ; install_location = ~/.xearthlayer/packages
 ; custom_scenery_path = /path/to/X-Plane 12/Custom Scenery
 ; auto_install_overlays = true
+; disable_overlays = false
 ; temp_dir = ~/Downloads/xearthlayer-temp
 
 [patches]
@@ -699,6 +703,7 @@ Run 'xearthlayer config upgrade' to update your configuration.
 | `packages.install_location` | path | Package installation directory |
 | `packages.custom_scenery_path` | path | Custom Scenery for overlays |
 | `packages.auto_install_overlays` | `true`, `false` | Auto-install matching overlays |
+| `packages.disable_overlays` | `true`, `false` | Suppress XEL overlays at runtime |
 | `packages.temp_dir` | path | Temporary download directory |
 | `logging.file` | path | Log file location |
 

xearthlayer-cli/src/commands/packages/args.rs

@@ -160,6 +160,11 @@ pub struct InstallArgs {
     pub custom_scenery_path: Option<PathBuf>,
     /// Automatically install overlay package when installing ortho for the same region.
     pub auto_install_overlays: bool,
+    /// Skip rebuild of the consolidated `yzXEL_overlay/` symlink folder when
+    /// true. The package is still downloaded and installed; only the symlink
+    /// folder X-Plane reads is left alone. The next `xearthlayer run` will
+    /// remove any stale folder. See `packages.disable_overlays` config key.
+    pub disable_overlays: bool,
     /// Number of concurrent part downloads.
     pub concurrent_downloads: usize,
 }
@@ -174,6 +179,8 @@ pub struct UpdateArgs {
     pub all: bool,
     /// Path to X-Plane Custom Scenery directory for overlay symlinks.
     pub custom_scenery_path: Option<PathBuf>,
+    /// See `InstallArgs::disable_overlays`.
+    pub disable_overlays: bool,
     /// Number of concurrent part downloads.
     pub concurrent_downloads: usize,
 }
@@ -186,6 +193,8 @@ pub struct RemoveArgs {
     pub force: bool,
     /// Path to X-Plane Custom Scenery directory for overlay symlinks.
     pub custom_scenery_path: Option<PathBuf>,
+    /// See `InstallArgs::disable_overlays`.
+    pub disable_overlays: bool,
 }
 
 /// Arguments for the info command.

xearthlayer-cli/src/commands/packages/handlers.rs

@@ -188,8 +188,19 @@ impl CommandHandler for CheckHandler {
 fn rebuild_consolidated_overlay(
     install_dir: &std::path::Path,
     custom_scenery_path: &Option<std::path::PathBuf>,
+    disable_overlays: bool,
     ctx: &CommandContext<'_>,
 ) {
+    if disable_overlays {
+        // Per `packages.disable_overlays` the consolidated overlay is suppressed
+        // at runtime. We deliberately leave any existing folder alone here; the
+        // next `xearthlayer run` removes it during startup. Issue #152.
+        ctx.output.println(
+            "Note: packages.disable_overlays = true; skipping consolidated overlay rebuild. \
+             The folder will be removed on next 'xearthlayer run'.",
+        );
+        return;
+    }
     let Some(ref scenery_path) = custom_scenery_path else {
         ctx.output
             .println("Note: No Custom Scenery path configured. Overlay symlink not created.");
@@ -292,7 +303,12 @@ impl InstallHandler {
         ));
 
         // Rebuild consolidated overlay to include the newly installed overlay
-        rebuild_consolidated_overlay(&args.install_dir, &args.custom_scenery_path, ctx);
+        rebuild_consolidated_overlay(
+            &args.install_dir,
+            &args.custom_scenery_path,
+            args.disable_overlays,
+            ctx,
+        );
     }
 }
 
@@ -373,7 +389,12 @@ impl CommandHandler for InstallHandler {
         // Rebuild consolidated overlay for overlay packages
         if args.package_type == PackageType::Overlay {
             ctx.output.newline();
-            rebuild_consolidated_overlay(&args.install_dir, &args.custom_scenery_path, ctx);
+            rebuild_consolidated_overlay(
+                &args.install_dir,
+                &args.custom_scenery_path,
+                args.disable_overlays,
+                ctx,
+            );
         }
 
         // Auto-install overlay when installing ortho (if enabled)
@@ -543,7 +564,12 @@ impl CommandHandler for UpdateHandler {
         // Rebuild consolidated overlay if any overlay packages were updated
         if overlay_updated {
             ctx.output.newline();
-            rebuild_consolidated_overlay(&args.install_dir, &args.custom_scenery_path, ctx);
+            rebuild_consolidated_overlay(
+                &args.install_dir,
+                &args.custom_scenery_path,
+                args.disable_overlays,
+                ctx,
+            );
         }
 
         Ok(())
@@ -628,7 +654,12 @@ impl CommandHandler for RemoveHandler {
 
         // Rebuild consolidated overlay after removing an overlay package
         if args.package_type == PackageType::Overlay {
-            rebuild_consolidated_overlay(&args.install_dir, &args.custom_scenery_path, ctx);
+            rebuild_consolidated_overlay(
+                &args.install_dir,
+                &args.custom_scenery_path,
+                args.disable_overlays,
+                ctx,
+            );
         }
 
         Ok(())

xearthlayer-cli/src/commands/packages/mod.rs

@@ -154,6 +154,7 @@ pub fn run(command: PackagesCommands) -> Result<(), CliError> {
                 temp_dir: temp_dir.unwrap_or_else(|| default_temp_dir(&config)),
                 custom_scenery_path: default_custom_scenery_dir(&config),
                 auto_install_overlays: config.packages.auto_install_overlays,
+                disable_overlays: config.packages.disable_overlays,
                 concurrent_downloads: config.packages.concurrent_downloads,
             },
             &ctx,
@@ -175,6 +176,7 @@ pub fn run(command: PackagesCommands) -> Result<(), CliError> {
                 temp_dir: temp_dir.unwrap_or_else(|| default_temp_dir(&config)),
                 all,
                 custom_scenery_path: default_custom_scenery_dir(&config),
+                disable_overlays: config.packages.disable_overlays,
                 concurrent_downloads: config.packages.concurrent_downloads,
             },
             &ctx,
@@ -192,6 +194,7 @@ pub fn run(command: PackagesCommands) -> Result<(), CliError> {
                 install_dir: install_dir.unwrap_or_else(|| default_install_dir(&config)),
                 force,
                 custom_scenery_path: default_custom_scenery_dir(&config),
+                disable_overlays: config.packages.disable_overlays,
             },
             &ctx,
         ),

xearthlayer/src/config/defaults.rs

@@ -376,6 +376,7 @@ impl Default for ConfigFile {
                 install_location: None,
                 custom_scenery_path: None,
                 auto_install_overlays: false,
+                disable_overlays: false,
                 temp_dir: None,
                 concurrent_downloads: 5,
             },

xearthlayer/src/config/keys.rs

@@ -69,6 +69,7 @@ pub enum ConfigKey {
     PackagesInstallLocation,
     PackagesCustomSceneryPath,
     PackagesAutoInstallOverlays,
+    PackagesDisableOverlays,
     PackagesTempDir,
     PackagesConcurrentDownloads,
 
@@ -151,6 +152,7 @@ impl FromStr for ConfigKey {
             "packages.install_location" => Ok(ConfigKey::PackagesInstallLocation),
             "packages.custom_scenery_path" => Ok(ConfigKey::PackagesCustomSceneryPath),
             "packages.auto_install_overlays" => Ok(ConfigKey::PackagesAutoInstallOverlays),
+            "packages.disable_overlays" => Ok(ConfigKey::PackagesDisableOverlays),
             "packages.temp_dir" => Ok(ConfigKey::PackagesTempDir),
             "packages.concurrent_downloads" => Ok(ConfigKey::PackagesConcurrentDownloads),
 
@@ -228,6 +230,7 @@ impl ConfigKey {
             ConfigKey::PackagesInstallLocation => "packages.install_location",
             ConfigKey::PackagesCustomSceneryPath => "packages.custom_scenery_path",
             ConfigKey::PackagesAutoInstallOverlays => "packages.auto_install_overlays",
+            ConfigKey::PackagesDisableOverlays => "packages.disable_overlays",
             ConfigKey::PackagesTempDir => "packages.temp_dir",
             ConfigKey::PackagesConcurrentDownloads => "packages.concurrent_downloads",
             ConfigKey::LoggingFile => "logging.file",
@@ -347,6 +350,7 @@ impl ConfigKey {
             ConfigKey::PackagesAutoInstallOverlays => {
                 config.packages.auto_install_overlays.to_string()
             }
+            ConfigKey::PackagesDisableOverlays => config.packages.disable_overlays.to_string(),
             ConfigKey::PackagesTempDir => config
                 .packages
                 .temp_dir
@@ -495,6 +499,11 @@ impl ConfigKey {
                 config.packages.auto_install_overlays =
                     v == "true" || v == "1" || v == "yes" || v == "on";
             }
+            ConfigKey::PackagesDisableOverlays => {
+                let v = value.to_lowercase();
+                config.packages.disable_overlays =
+                    v == "true" || v == "1" || v == "yes" || v == "on";
+            }
             ConfigKey::PackagesTempDir => {
                 config.packages.temp_dir = optional_path(value);
             }
@@ -639,6 +648,7 @@ impl ConfigKey {
             ConfigKey::PackagesInstallLocation => Box::new(OptionalPathSpec),
             ConfigKey::PackagesCustomSceneryPath => Box::new(OptionalPathSpec),
             ConfigKey::PackagesAutoInstallOverlays => Box::new(BooleanSpec),
+            ConfigKey::PackagesDisableOverlays => Box::new(BooleanSpec),
             ConfigKey::PackagesTempDir => Box::new(OptionalPathSpec),
             ConfigKey::PackagesConcurrentDownloads => Box::new(IntegerRangeSpec::new(1, 10)),
             ConfigKey::LoggingFile => Box::new(PathSpec),
@@ -712,6 +722,7 @@ impl ConfigKey {
             ConfigKey::PackagesInstallLocation,
             ConfigKey::PackagesCustomSceneryPath,
             ConfigKey::PackagesAutoInstallOverlays,
+            ConfigKey::PackagesDisableOverlays,
             ConfigKey::PackagesTempDir,
             ConfigKey::PackagesConcurrentDownloads,
             ConfigKey::LoggingFile,
@@ -1250,6 +1261,38 @@ mod tests {
         assert!(key.validate("601").is_err());
     }
 
+    #[test]
+    fn test_packages_disable_overlays_round_trip() {
+        let key = ConfigKey::from_str("packages.disable_overlays").unwrap();
+        assert_eq!(key.name(), "packages.disable_overlays");
+        assert_eq!(key.section(), "packages");
+        assert!(!key.is_sensitive());
+
+        let mut config = ConfigFile::default();
+        // Default
+        assert_eq!(key.get(&config), "false");
+        assert!(!config.packages.disable_overlays);
+
+        // Accepts every truthy form the BooleanSpec allows
+        for truthy in &["true", "1", "yes", "on", "TRUE", "YES"] {
+            key.set(&mut config, truthy).unwrap();
+            assert!(
+                config.packages.disable_overlays,
+                "Expected '{}' to set true",
+                truthy
+            );
+        }
+        // And falsy
+        key.set(&mut config, "false").unwrap();
+        assert!(!config.packages.disable_overlays);
+
+        // Validation rejects garbage
+        assert!(key.validate("maybe").is_err());
+
+        // Listed in all()
+        assert!(ConfigKey::all().contains(&ConfigKey::PackagesDisableOverlays));
+    }
+
     #[test]
     fn test_new_prefetch_keys_in_all() {
         let all = ConfigKey::all();

xearthlayer/src/config/parser.rs

@@ -272,6 +272,9 @@ pub(super) fn parse_ini(ini: &Ini) -> Result<ConfigFile, ConfigFileError> {
         if let Some(v) = section.get("auto_install_overlays") {
             config.packages.auto_install_overlays = parse_bool(v);
         }
+        if let Some(v) = section.get("disable_overlays") {
+            config.packages.disable_overlays = parse_bool(v);
+        }
         if let Some(v) = section.get("temp_dir") {
             let v = v.trim();
             if !v.is_empty() {

xearthlayer/src/config/settings.rs

@@ -160,6 +160,12 @@ pub struct PackagesSettings {
     pub custom_scenery_path: Option<PathBuf>,
     /// Automatically install overlay packages when installing ortho for same region.
     pub auto_install_overlays: bool,
+    /// Suppress the consolidated `yzXEL_overlay/` symlink folder in Custom Scenery
+    /// at runtime. Overlay packages are still downloaded and stored locally; this
+    /// only controls whether X-Plane sees the consolidated overlay folder when
+    /// `xearthlayer run` starts. Useful when running third-party overlay scenery
+    /// (e.g., SimHeaven) that would otherwise conflict with XEL overlays.
+    pub disable_overlays: bool,
     /// Temporary directory for downloads (default: ~/.xearthlayer/tmp).
     pub temp_dir: Option<PathBuf>,
     /// Number of concurrent part downloads (1-10, default: 5).

xearthlayer/src/config/writer.rs

@@ -36,6 +36,11 @@ pub(super) fn to_config_string(config: &ConfigFile) -> String {
     } else {
         "false"
     };
+    let disable_overlays = if config.packages.disable_overlays {
+        "true"
+    } else {
+        "false"
+    };
     let temp_dir = config
         .packages
         .temp_dir
@@ -151,6 +156,12 @@ install_location = {}
 custom_scenery_path = {}
 ; Automatically install overlay packages when installing ortho for same region
 auto_install_overlays = {}
+; Suppress XEL overlays at runtime by removing the consolidated yzXEL_overlay/
+; symlink folder from Custom Scenery on `xearthlayer run` startup. Overlay
+; packages are still downloaded and stored locally — only the symlink that
+; X-Plane reads is suppressed. Use this when running third-party overlay
+; scenery (e.g., SimHeaven) that conflicts with XEL overlays. (default: false)
+disable_overlays = {}
 ; Temporary directory for package downloads (default: ~/.xearthlayer/tmp)
 ; Large packages are downloaded here before extraction
 temp_dir = {}
@@ -280,6 +291,7 @@ congestion_threshold = {}
         install_location,
         custom_scenery_path,
         auto_install_overlays,
+        disable_overlays,
         temp_dir,
         config.packages.concurrent_downloads,
         path_to_string(&config.logging.file),

xearthlayer/src/service/orchestrator/core.rs

@@ -11,7 +11,8 @@ use crate::aircraft_position::{SharedAircraftPosition, StateAggregator};
 use crate::geo_index::GeoIndex;
 use crate::log::TracingLogger;
 use crate::manager::{
-    create_consolidated_overlay, InstalledPackage, LocalPackageStore, MountManager, ServiceBuilder,
+    create_consolidated_overlay, remove_consolidated_overlay, InstalledPackage, LocalPackageStore,
+    MountManager, ServiceBuilder,
 };
 use crate::metrics::TelemetrySnapshot;
 use crate::ortho_union::OrthoUnionIndex;
@@ -232,16 +233,33 @@ impl ServiceOrchestrator {
             )));
         }
 
-        // Phase 2: Create overlay symlinks
+        // Phase 2: Create overlay symlinks (or remove them if disabled)
         if let Some(ref cb) = callback {
             cb(StartupProgress::CreatingOverlay);
         }
-        let overlay_result = create_consolidated_overlay(store, &self.config.custom_scenery_path);
-        let overlay_success = overlay_result.success;
-        let overlay_error = overlay_result.error.clone();
-        if let Some(ref error) = overlay_result.error {
-            tracing::warn!(error = %error, "Failed to create consolidated overlay");
-        }
+        let (overlay_success, overlay_error) = if self.config.disable_overlays {
+            match remove_consolidated_overlay(&self.config.custom_scenery_path) {
+                Ok(true) => {
+                    tracing::info!(
+                        "Removed consolidated overlay folder (packages.disable_overlays = true); \
+                         X-Plane will not load XEarthLayer overlays this session"
+                    );
+                    (true, None)
+                }
+                Ok(false) => (true, None),
+                Err(e) => {
+                    tracing::warn!(error = %e, "Failed to remove consolidated overlay");
+                    (false, Some(e.to_string()))
+                }
+            }
+        } else {
+            let overlay_result =
+                create_consolidated_overlay(store, &self.config.custom_scenery_path);
+            if let Some(ref error) = overlay_result.error {
+                tracing::warn!(error = %error, "Failed to create consolidated overlay");
+            }
+            (overlay_result.success, overlay_result.error.clone())
+        };
 
         // Phase 3: Start APT telemetry
         if let Some(ref cb) = callback {