Commit local changes (menu refactor, home updates, built-in catalog spec)

Author: Hongwei-MB

README.md

@@ -279,6 +279,8 @@ nuke publish-libs
 | `Agibuild.Modulus.Cli` | CLI tool |
 | `Agibuild.Modulus.Templates` | Project templates |
 
+> Note: `modulus new` generates a `Directory.Build.props` with `ModulusCliLibDir` so newly generated modules can compile against the same Modulus assemblies shipped with the CLI.
+
 ## Contributing
 
 Pull requests and issues are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

README.zh-CN.md

@@ -279,6 +279,8 @@ nuke publish-libs
 | `Agibuild.Modulus.Cli` | CLI 工具 |
 | `Agibuild.Modulus.Templates` | 项目模板 |
 
+> 说明：`modulus new` 会生成 `Directory.Build.props`，通过 `ModulusCliLibDir` 从 CLI 安装目录解析 `Modulus.*.dll`，确保新生成的模块可直接编译通过。
+
 ## 贡献
 
 欢迎提交 Issue 和 PR！请参阅 [CONTRIBUTING.zh-CN.md](./CONTRIBUTING.zh-CN.md)。

docs/getting-started.md

@@ -175,13 +175,14 @@ The manifest file is automatically generated by the template and contains:
   <Assets>
     <!-- Module assemblies -->
     <Asset Type="Modulus.Package" Path="MyFirstModule.Core.dll" />
+
+    <!-- Host-specific UI packages -->
+    <Asset Type="Modulus.Package" Path="MyFirstModule.UI.Avalonia.dll" TargetHost="Modulus.Host.Avalonia" />
+    <Asset Type="Modulus.Package" Path="MyFirstModule.UI.Blazor.dll" TargetHost="Modulus.Host.Blazor" />
 
-    <!-- Menu registration -->
-    <Asset Type="Modulus.Menu" 
-           Id="myfirstmodule-main" 
-           DisplayName="My First Module"
-           Icon="Folder"
-           Route="MyFirstModule.ViewModels.MainViewModel" />
+    <!-- Menu declarations are NOT in the manifest anymore.
+         Menus are declared via [AvaloniaMenu]/[BlazorMenu] on the host-specific module entry type
+         and projected to the database at install/update time. -->
   </Assets>
 </PackageManifest>
 ```
@@ -271,7 +272,12 @@ dotnet restore
 
 ### Module not appearing in menu
 
-Check that your manifest has the correct `Modulus.Menu` asset with a valid `Route` pointing to your ViewModel.
+Check that your host-specific module entry type declares a menu attribute:
+
+- Avalonia: `[AvaloniaMenu("key", "Display", typeof(MainViewModel), ...)]`
+- Blazor: `[BlazorMenu("key", "Display", "/route", ...)]`
+
+Menus are read from the database at render time. If you upgraded from an older build, delete the host database file and restart.
 
 ## Getting Help
 

docs/getting-started.zh-CN.md

@@ -175,13 +175,14 @@ dotnet run --project path/to/Modulus/src/Hosts/Modulus.Host.Avalonia
   <Assets>
     <!-- 模块程序集 -->
     <Asset Type="Modulus.Package" Path="MyFirstModule.Core.dll" />
+
+    <!-- Host-specific UI packages -->
+    <Asset Type="Modulus.Package" Path="MyFirstModule.UI.Avalonia.dll" TargetHost="Modulus.Host.Avalonia" />
+    <Asset Type="Modulus.Package" Path="MyFirstModule.UI.Blazor.dll" TargetHost="Modulus.Host.Blazor" />
 
-    <!-- 菜单注册 -->
-    <Asset Type="Modulus.Menu" 
-           Id="myfirstmodule-main" 
-           DisplayName="我的第一个模块"
-           Icon="Folder"
-           Route="MyFirstModule.ViewModels.MainViewModel" />
+    <!-- 菜单不再在清单中声明。
+         菜单通过 host-specific 模块入口类型上的 [AvaloniaMenu]/[BlazorMenu] 声明，
+         并在安装/启动同步时投影到数据库。 -->
   </Assets>
 </PackageManifest>
 ```
@@ -271,7 +272,12 @@ dotnet restore
 
 ### 模块未出现在菜单中
 
-检查您的清单是否具有正确的 `Modulus.Menu` 资产，其 `Route` 指向您的 ViewModel。
+检查 host-specific 模块入口类型是否声明了菜单属性：
+
+- Avalonia：`[AvaloniaMenu("key", "Display", typeof(MainViewModel), ...)]`
+- Blazor：`[BlazorMenu("key", "Display", "/route", ...)]`
+
+导航菜单渲染时只读取数据库。如从旧版本升级，请删除 Host 的数据库文件后重启。
 
 ## 获取帮助
 

docs/module-development.md

@@ -257,15 +257,9 @@ public class MyModuleAvaloniaModule : ModulusPackage
            TargetHost="Modulus.Host.Avalonia" />
     <Asset Type="Modulus.Package" Path="MyModule.UI.Blazor.dll" 
            TargetHost="Modulus.Host.Blazor" />
-    
-    <!-- Menu items -->
-    <Asset Type="Modulus.Menu" 
-           Id="mymodule-main" 
-           DisplayName="My Module"
-           Icon="Folder"
-           Route="MyModule.ViewModels.MainViewModel"
-           Location="Main"
-           Order="100" />
+
+    <!-- Menu items are NOT declared in the manifest anymore.
+         They are declared via attributes on the host-specific module entry type and projected to DB at install/update time. -->
   </Assets>
 </PackageManifest>
 ```
@@ -280,18 +274,16 @@ public class MyModuleAvaloniaModule : ModulusPackage
 
 ### Multiple Menus
 
-```xml
-<Assets>
-  <Asset Type="Modulus.Menu" Id="mymodule-main" 
-         DisplayName="Dashboard" Icon="Home" 
-         Route="MyModule.ViewModels.DashboardViewModel" 
-         Location="Main" Order="10" />
-         
-  <Asset Type="Modulus.Menu" Id="mymodule-settings" 
-         DisplayName="Settings" Icon="Settings" 
-         Route="MyModule.ViewModels.SettingsViewModel" 
-         Location="Bottom" Order="100" />
-</Assets>
+```csharp
+// Avalonia UI module entry
+[AvaloniaMenu("dashboard", "Dashboard", typeof(DashboardViewModel), Icon = IconKind.Home, Location = MenuLocation.Main, Order = 10)]
+[AvaloniaMenu("settings", "Settings", typeof(SettingsViewModel), Icon = IconKind.Settings, Location = MenuLocation.Bottom, Order = 100)]
+public sealed class MyModuleAvaloniaModule : ModulusPackage { }
+
+// Blazor UI module entry
+[BlazorMenu("dashboard", "Dashboard", "/dashboard", Icon = IconKind.Home, Location = MenuLocation.Main, Order = 10)]
+[BlazorMenu("settings", "Settings", "/settings", Icon = IconKind.Settings, Location = MenuLocation.Bottom, Order = 100)]
+public sealed class MyModuleBlazorModule : ModulusPackage { }
 ```
 
 ## Testing

openspec/changes/add-built-in-module-catalog-security/design.md

@@ -0,0 +1,131 @@
+# Design: Built-in module catalog security and dev-mode integrity policy
+
+## Scope
+本设计覆盖：
+- 自带模块（Built-in / System modules）如何由 Host 项目引用确定、随应用发布、启动时入库、并进行完整性校验以防替换。
+- Development 环境下的完整性策略（仅校验程序集名/强名称，仍使用 `{AppBaseDir}/Modules/`）。
+- 系统模块不可卸载/不可禁用的强制规则（多层防线 + 启动自修复）。
+- 用户模块防回滚（仅用户模块），数据存 DB。
+
+不在本设计范围：
+- 自带模块独立更新、签名分发、模块市场、供应链签名验证。
+- 兼容旧模块/旧数据库（本版本不兼容）。
+
+## Definitions
+- **Built-in module / System module**：随 Host 应用一起发布的模块集合，来源是 Host `.csproj` 的 `ProjectReference` 列表（build-time）。
+- **User module**：安装在用户目录的模块集合（可卸载/可禁用）。
+- **Catalog**：不可篡改的自带模块清单，编译进 Host 程序集，作为 allowlist。
+- **Integrity check**：对模块包（manifest + 目标程序集）的校验，用于防止“替换模块文件”。
+- **HostType**：例如 `Modulus.Host.Avalonia` / `Modulus.Host.Blazor`。
+- **AppBaseDir**：`AppContext.BaseDirectory`。
+
+## Goals
+- **G1**：自带模块集合必须由 Host 项目引用确定，不允许通过扫描 `{AppBaseDir}/Modules/` 注入。
+- **G2**：Production 环境下，自带模块必须通过强完整性校验（SHA256）才能入库并加载。
+- **G3**：Development 环境下（`DOTNET_ENVIRONMENT=Development`），允许频繁编译导致 hash 变化，但仍要限制注入面（仅允许 allowlist + 程序集名/强名称校验 + 必须在 `{AppBaseDir}/Modules/`）。
+- **G4**：系统模块不允许卸载、不允许禁用；即使 DB 被篡改也能自修复。
+- **G5**：菜单渲染只来自 DB；模块属性只用于入库/安装/启动同步阶段投影。
+- **G6**：防回滚仅针对用户模块，状态存 DB，install/update 时拒绝降级。
+
+## Non-Goals
+- **NG1**：不处理攻击者具备写入/替换 Host 程序集的场景（那属于 OS 权限与应用签名问题）。
+- **NG2**：不支持“系统模块在用户目录 overlay 更新”的机制。
+
+## Architecture
+
+### A) Built-in Module Catalog
+Catalog 由构建阶段生成并编译进 Host（建议在 Host 工程下生成 `BuiltInModuleCatalog.g.cs`）：
+
+- **Input**：Host `.csproj` 中标记为 built-in 的 `ProjectReference`（推荐通过 item metadata，例如 `ModulusBuiltIn="true"`）。
+- **Output**：`BuiltInModuleCatalog`（强类型）包含 entries：
+  - `ModuleId`（GUID string）
+  - `ModuleName`
+  - `RelativePackageDir`：固定 `Modules/{ModuleName}/`
+  - `ManifestSha256`（Production 用）
+  - `Files`：每个文件 `RelativePath + Sha256 + AssemblyIdentity(可选)`
+  - `Hosts`：该模块支持的 host（用于选择 UI 目标程序集）
+
+**关键约束**：
+- Runtime 绝不通过扫描 `{AppBaseDir}/Modules` 发现系统模块。
+- 系统模块加载路径不信任 DB，只信 Catalog 的 `{AppBaseDir}/{RelativePackageDir}`。
+
+### B) Integrity policy (Production vs Development)
+依据 `DOTNET_ENVIRONMENT` 判定：
+- `Development`：Dev policy
+- 其它：Production policy
+
+#### Production policy
+- **必须校验**：
+  - `extension.vsixmanifest` SHA256 == `Catalog.ManifestSha256`
+  - 当前 HostType 需要加载的目标程序集（例如 `*.UI.Blazor.dll` 或 `*.UI.Avalonia.dll`）SHA256 == Catalog 记录
+  - `*.Core.dll`（如果属于系统模块包的一部分且会被加载）SHA256 == Catalog 记录
+- **失败处理**：
+  - 不入库（或将模块标记为 `Tampered`）
+  - 不加载
+  - 记录可诊断日志
+
+#### Development policy
+为了不阻断开发迭代：
+- **路径约束**：仍必须位于 `{AppBaseDir}/Modules/{ModuleName}/`（禁止从用户目录覆盖系统模块）。
+- **程序集校验**：不做 SHA256；仅校验目标程序集的：
+  - `AssemblyName.Name` 匹配 Catalog 期望值
+  - StrongName 公钥（或 PublicKeyToken）匹配 Catalog 期望值（若程序集是强签名）
+  - 若程序集未强签名，则仅做 `AssemblyName.Name` 校验并产生 warning（显式提示风险仅限开发环境）
+- **manifest 校验**：
+  - 校验 manifest 中的 `ModuleId` 必须等于 Catalog 的 `ModuleId`
+  - 校验 `InstallationTarget` 包含当前 HostType（并校验 Version range 满足当前 HostVersion）
+  - 不校验 manifest SHA256（避免改 manifest 时阻断开发）
+
+> 以上满足你要求：Development 模式仅校验程序集名/强名称，且仍使用 `{AppBaseDir}/Modules/`。
+
+### C) Startup sync (2B) and menu projection
+启动链路（DB migrate 之后、模块加载之前）执行：
+
+1. `SyncBuiltInModulesAsync(hostType)`
+   - 遍历 Catalog entries（仅 allowlist）
+   - 计算模块 package dir：`{AppBaseDir}/{RelativePackageDir}`
+   - 依据环境执行完整性校验（Prod/Dev policy）
+   - 通过校验后执行 2B 入库：
+     - 触发条件：
+       - DB 无该模块
+       - `ManifestHash` !=（Production：Catalog manifest sha；Development：可跳过此项，仅在缺失时写）
+       - 当前 hostType 的菜单记录缺失
+     - 动作：
+       - Upsert `ModuleEntity`：强制 `IsSystem=true`、`IsEnabled=true`、`Path` 写为相对路径（如 `Modules/{ModuleName}/` 或 manifest 相对路径）
+       - `ReplaceModuleMenusAsync`：使用 metadata-only 读取菜单属性写库
+2. `Integrity check`（若系统已有 checker）：
+   - 对系统模块：额外验证 `DB.Path` 不参与路径决策；仅用于展示/诊断
+3. 加载阶段：
+   - 从 DB 查询 `IsEnabled=true && State=Ready` 的模块
+   - 对 `IsSystem=true`：加载路径来自 Catalog
+
+### D) System module enforcement
+系统模块强制规则：
+- 禁止卸载（uninstall）
+- 禁止禁用（disable）
+- 启动自修复：若 DB 中系统模块 `IsEnabled=false` 或 `IsSystem=false` → 纠正并记录 warning
+
+强制点（多层）：
+- `IModuleInstallerService` / uninstall service：拒绝
+- `IModuleRepository` 写入路径：系统模块写入时强制字段
+- CLI 命令层：拒绝并返回明确错误
+- UI 操作入口：隐藏或置灰（但不能只靠 UI）
+
+### E) User module anti-rollback (DB-backed)
+仅针对用户模块（用户目录可写）：
+- DB 存储 per-module 的最大已接受版本（推荐 SemVer 比较）：
+  - `UserModulePolicyEntity`：`ModuleId`, `MaxAcceptedVersion`, `UpdatedAt`
+- 安装/更新时：
+  - 若 `incomingVersion < MaxAcceptedVersion` → 拒绝（默认）
+  - 若安装成功且版本更高 → 更新 `MaxAcceptedVersion`
+- 可选：提供 `--force` 仅用于开发/测试（默认生产环境关闭，或需要显式配置开启）
+
+## Operational notes
+- 对系统模块，“防替换”依赖应用安装目录写权限与 Production 校验共同生效。
+- Development 政策必须显式由 `DOTNET_ENVIRONMENT=Development` 开启，避免误入生产。
+
+## Open Questions
+- 系统模块 DLL 是否全部强签名？若不是，Development 下强名称校验只能部分生效，需要定义 warning 策略。
+- User module 的版本比较使用何种 SemVer 实现与规范（NuGet.Versioning 推荐）。
+
+

openspec/changes/add-built-in-module-catalog-security/proposal.md

@@ -0,0 +1,29 @@
+# Change: Add built-in module catalog security and dev-mode integrity policy
+
+## Why
+- 自带模块与应用绑定，必须防止“投放/替换”模块文件带来的安全风险。
+- 菜单渲染只读数据库，自带模块需要在启动时可靠入库、可诊断、可控。
+- 开发阶段频繁编译会导致 hash 变化，需要一个明确的 Development 策略避免开发体验崩坏。
+- 防回滚主要针对用户模块（用户目录可写），自带模块随应用更新不需要单独防回滚。
+
+## What Changes
+- **Built-in Module Catalog**：Host build-time 依据 `ProjectReference` 生成不可篡改的自带模块清单（编译进 Host）。
+- **Integrity policy**：
+  - Production：自带模块的 `extension.vsixmanifest` 与目标程序集文件 SHA256 必须与 Catalog 匹配，否则拒绝入库/加载。
+  - Development（`DOTNET_ENVIRONMENT=Development`）：自带模块不做 SHA256 校验，仅校验程序集名/强名称（且仍要求位于 `{AppBaseDir}/Modules/`）。
+- **System module enforcement**：自带模块 `IsSystem=true` 且 **不允许卸载/禁用**，任何操作请求直接拒绝并在启动时自修复。
+- **Menu projection**：自带模块按方案 2B（缺失/变更/菜单缺失才投影）在启动时入库；导航渲染只读 DB。
+- **User module anti-rollback**：仅对用户模块启用防回滚策略（保存到 DB 并在 install/update 时拒绝降级）。
+- **No backward compatibility**：不兼容旧数据与旧逻辑；对旧数据库结构/旧菜单来源失败快并提示删除数据库。
+
+## Impact
+- Affected specs:
+  - `openspec/specs/runtime/spec.md`
+  - `openspec/specs/module-packaging/spec.md`
+- Affected code (implementation stage):
+  - Host build pipeline (MSBuild/Nuke) for catalog generation
+  - `Modulus.Core.Runtime` startup sync & integrity gates
+  - `Modulus.Core.Installation` for projection triggers
+  - DB schema for user module anti-rollback
+
+

openspec/changes/add-built-in-module-catalog-security/specs/module-packaging/spec.md

@@ -0,0 +1,33 @@
+# module-packaging Specification (delta)
+
+## ADDED Requirements
+
+### Requirement: User module anti-rollback stored in database
+用户模块安装/更新 MUST 实施防回滚策略：系统 SHALL 在数据库中记录每个用户模块的最大已接受版本，并在安装时拒绝降级。
+
+#### Scenario: Install higher version updates max accepted version
+- **WHEN** 用户安装用户模块版本 `1.2.0`
+- **AND** 数据库中该模块的 `MaxAcceptedVersion` 不存在或小于 `1.2.0`
+- **THEN** 安装成功
+- **AND** 数据库将 `MaxAcceptedVersion` 更新为 `1.2.0`。
+
+#### Scenario: Install lower version is rejected as rollback
+- **WHEN** 数据库中用户模块 `MaxAcceptedVersion` 为 `1.2.0`
+- **AND** 用户尝试安装版本 `1.1.0`
+- **THEN** 安装失败
+- **AND** 输出错误：检测到回滚安装（downgrade）被拒绝。
+
+## MODIFIED Requirements
+
+### Requirement: Built-in module selection via host project references
+构建系统 SHALL 允许 Host 通过项目引用选择“随应用发布”的内置模块集合，并生成不可篡改的 Built-in Module Catalog；运行时不将模块程序集加载进默认 ALC，且系统模块不依赖目录扫描发现。
+
+#### Scenario: Host includes built-in modules without referencing output assembly
+- **WHEN** Host 项目引用一个内置模块项目
+- **THEN** 该引用使用 `ProjectReference` 并设置 `ReferenceOutputAssembly="false"`
+- **AND** 构建输出将模块产物输出到 `artifacts/bin/Modules/{ModuleName}/`
+- **AND** 发布时将该模块复制到 `{AppBaseDir}/Modules/{ModuleName}/`
+- **AND** 构建阶段生成 Built-in Module Catalog（包含 ModuleId、相对路径与完整性信息）并编译进 Host
+- **AND** Host 运行时仍由 `ModuleLoader` 在独立 ALC 中加载该模块（不经默认 ALC）。
+
+