fix(host-sdk): align default module directories with CLI

Author: Hongwei-MB

docs/host-app-development.md

@@ -127,16 +127,17 @@ The generated templates use `ModulusHostSdkBuilder.AddDefaultModuleDirectories()
 
 - **System modules**: `{AppBaseDir}/Modules`
 - **User modules (Windows)**: `%APPDATA%/Modulus/Modules`
-- **User modules (macOS/Linux)**: `Environment.SpecialFolder.ApplicationData/Modulus/Modules`
+- **User modules (macOS/Linux)**: `~/.modulus/Modules`
 
-### Align the host with the CLI default on macOS/Linux
+### CLI alignment note
 
 The Modulus CLI installs modules under:
 
 - Windows: `%APPDATA%/Modulus/Modules`
 - macOS/Linux: `~/.modulus/Modules`
 
-If you want your host to load modules installed by the CLI on macOS/Linux, add the `.modulus` directory explicitly:
+The default Host App templates are aligned with this location.
+If you are building a custom host and need to add it explicitly:
 
 ```csharp
 using Modulus.Core.Paths;

docs/host-app-development.zh-CN.md

@@ -78,16 +78,15 @@ Host 模板使用：
 
 - 系统模块：`{AppBaseDir}/Modules`
 - 用户模块（Windows）：`%APPDATA%/Modulus/Modules`
-- 用户模块（macOS/Linux）：`Environment.SpecialFolder.ApplicationData/Modulus/Modules`
+- 用户模块（macOS/Linux）：`~/.modulus/Modules`
 
 CLI 默认安装路径为：
 
 - Windows：`%APPDATA%/Modulus/Modules`
 - macOS/Linux：`~/.modulus/Modules`
 
-因此在 macOS/Linux 上，**Host 默认不会自动加载** CLI 安装到 `~/.modulus/Modules` 的模块。
-
-如果你希望 Host 在 macOS/Linux 上也能直接加载 CLI 安装的模块，请在 Host 代码里额外加入 `.modulus` 目录：
+默认 Host App 模板已经与 CLI 安装目录对齐。
+如果你在自定义 Host 中需要显式加入该目录，可以在 Host 代码里添加：
 
 ```csharp
 using Modulus.Core.Paths;

src/Modulus.HostSdk.Runtime/ModulusHostSdkBuilder.cs

@@ -4,6 +4,7 @@
 using Modulus.Core;
 using Modulus.Core.Data;
 using Modulus.Core.Installation;
+using Modulus.Core.Paths;
 using Modulus.Core.Runtime;
 using Modulus.HostSdk.Abstractions;
 using Modulus.Infrastructure.Data.Repositories;
@@ -37,18 +38,26 @@ public ModulusHostSdkBuilder(IServiceCollection services, IConfiguration configu
     /// <summary>
     /// Adds default module directories:
     /// - {AppBaseDir}/Modules (system)
-    /// - %APPDATA%/Modulus/Modules (user)
+    /// - {UserRoot}/Modules (user)
     /// </summary>
     public ModulusHostSdkBuilder AddDefaultModuleDirectories()
     {
         var appModules = Path.Combine(AppContext.BaseDirectory, "Modules");
         _moduleDirectories.Add(new HostModuleDirectory(appModules, IsSystem: true));
 
-        var userModules = Path.Combine(
+        // Canonical user modules directory: align with Modulus.Core.Paths.LocalStorage (Windows: %APPDATA%/Modulus; others: $HOME/.modulus).
+        var userModules = Path.Combine(LocalStorage.GetUserRoot(), "Modules");
+        _moduleDirectories.Add(new HostModuleDirectory(userModules, IsSystem: false));
+
+        // Backward compatibility: some hosts may have used ApplicationData directly on non-Windows before LocalStorage aligned paths.
+        var legacyUserModules = Path.Combine(
             Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
             "Modulus",
             "Modules");
-        _moduleDirectories.Add(new HostModuleDirectory(userModules, IsSystem: false));
+        if (!IsSameDirectory(userModules, legacyUserModules))
+        {
+            _moduleDirectories.Add(new HostModuleDirectory(legacyUserModules, IsSystem: false));
+        }
 
         return this;
     }
@@ -86,8 +95,12 @@ public async Task<IModulusApplication> BuildAsync<TStartupModule>(ILoggerFactory
     {
         ArgumentNullException.ThrowIfNull(loggerFactory);
 
-        // Filter directories that actually exist to avoid noisy warnings.
+        // Filter directories that actually exist (and de-duplicate paths) to avoid noisy warnings and double-scanning.
+        var pathComparer = OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal;
         var dirs = _moduleDirectories
+            .Select(d => new { Dir = d, NormalizedPath = NormalizeDirectoryPath(d.Path) })
+            .GroupBy(x => x.NormalizedPath, pathComparer)
+            .Select(g => g.OrderByDescending(x => x.Dir.IsSystem).First().Dir)
             .Where(d => Directory.Exists(d.Path))
             .Select(d => new ModuleDirectory(d.Path, d.IsSystem))
             .ToList();
@@ -103,6 +116,18 @@ public async Task<IModulusApplication> BuildAsync<TStartupModule>(ILoggerFactory
 
         return app;
     }
+
+    private static string NormalizeDirectoryPath(string path)
+    {
+        var full = Path.GetFullPath(path);
+        return full.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+    }
+
+    private static bool IsSameDirectory(string a, string b)
+    {
+        var comparer = OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal;
+        return comparer.Equals(NormalizeDirectoryPath(a), NormalizeDirectoryPath(b));
+    }
 }
 
 

tests/Modulus.HostSdk.Tests/HostSdkBuilderTests.cs

@@ -6,6 +6,8 @@
 using Modulus.HostSdk.Runtime;
 using Modulus.Sdk;
 using Modulus.Core.Architecture;
+using Modulus.Core.Paths;
+using System.Reflection;
 
 namespace Modulus.HostSdk.Tests;
 
@@ -16,7 +18,7 @@ private sealed class TestHostModule : ModulusPackage
     }
 
     [Fact]
-    public void AddDefaultModuleDirectories_AddsTwoDirectories()
+    public void AddDefaultModuleDirectories_AddsExpectedDefaultDirectories()
     {
         var services = new ServiceCollection();
         var config = new ConfigurationBuilder().Build();
@@ -33,8 +35,24 @@ public void AddDefaultModuleDirectories_AddsTwoDirectories()
 
         Assert.True(builder.Options.ModuleDirectories.Count == 0, "Options.ModuleDirectories should not be mutated by builder methods.");
 
-        // We can't access the builder's private list; this test is mainly a behavioral guard that it doesn't throw and is chainable.
-        Assert.NotNull(builder);
+        // Validate defaults via reflection (avoid adding public API solely for tests).
+        var list = GetPrivateModuleDirectories(builder);
+
+        var systemDir = Path.Combine(AppContext.BaseDirectory, "Modules");
+        var userDir = Path.Combine(LocalStorage.GetUserRoot(), "Modules");
+        var legacyUserDir = Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
+            "Modulus",
+            "Modules");
+
+        Assert.Contains(list, d => d.IsSystem && PathEquals(d.Path, systemDir));
+        Assert.Contains(list, d => !d.IsSystem && PathEquals(d.Path, userDir));
+
+        // Only included when distinct from the canonical user directory.
+        if (!PathEquals(userDir, legacyUserDir))
+        {
+            Assert.Contains(list, d => !d.IsSystem && PathEquals(d.Path, legacyUserDir));
+        }
     }
 
     [Fact]
@@ -154,6 +172,29 @@ public async Task BuildAsync_CreatesApplication()
             try { Directory.Delete(tempDir, recursive: true); } catch { }
         }
     }
+
+    private static List<HostModuleDirectory> GetPrivateModuleDirectories(ModulusHostSdkBuilder builder)
+    {
+        var field = typeof(ModulusHostSdkBuilder).GetField("_moduleDirectories", BindingFlags.Instance | BindingFlags.NonPublic);
+        Assert.NotNull(field);
+
+        var value = field!.GetValue(builder);
+        Assert.NotNull(value);
+
+        return Assert.IsAssignableFrom<List<HostModuleDirectory>>(value);
+    }
+
+    private static bool PathEquals(string a, string b)
+    {
+        var comparer = OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal;
+        return comparer.Equals(Normalize(a), Normalize(b));
+    }
+
+    private static string Normalize(string path)
+    {
+        var full = Path.GetFullPath(path);
+        return full.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+    }
 }