refactor(cli): command-handler architecture and in-process tests

Author: Hongwei-MB

build/coverage.cobertura.runsettings

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<RunSettings>
+  <DataCollectionRunSettings>
+    <DataCollectors>
+      <DataCollector friendlyName="XPlat Code Coverage">
+        <Configuration>
+          <Format>cobertura</Format>
+        </Configuration>
+      </DataCollector>
+    </DataCollectors>
+  </DataCollectionRunSettings>
+</RunSettings>
+

openspec/changes/refactor-cli-command-architecture/design.md

@@ -0,0 +1,52 @@
+## Context
+`Modulus.Cli` 目前存在两类测试路径：
+- `install/uninstall/list` 已经具备 handler 形态（`Commands/Handlers/*`），测试可以直接调用 handler 并注入 `ServiceProvider`，因此覆盖率可统计。
+- `new/build/pack` 以进程执行为主（测试通过 `dotnet "<modulus.dll>" ...` 跑 CLI），导致覆盖率采集只覆盖测试进程，`Modulus.Cli` 关键文件几乎为 0%。
+
+本变更的核心是统一架构与依赖注入方式，使所有命令均可 in-process 执行并被覆盖率工具准确统计。
+
+## Goals / Non-Goals
+- Goals
+  - 统一 `Modulus.Cli` 为 **Command -> Handler** 架构。
+  - 将外部副作用（Console/IO/Process）隔离到可替换抽象，支持测试注入与可重复执行。
+  - 让 CLI 集成测试可 **in-process** 覆盖 `new/build/pack/install/uninstall/list` 的主路径。
+  - 将 `Modulus.Cli\` 行覆盖率提升到 **>= 95%**（以关键路径为准）。
+- Non-Goals
+  - 不改变 CLI 的用户可见行为（参数、默认输出文案、目录结构）除非为修复 bug。
+  - 不引入重量级命令行 UI 框架（例如迁移到 Spectre.Console）作为本变更前置条件。
+  - 不在本变更内重写 `dotnet build` 本身的行为；只提供可测试的“进程执行适配层”。
+
+## Decisions
+- Decision: 命令逻辑全部下沉到 Handler
+  - 每个命令对应一个 handler（例如 `NewHandler` / `BuildHandler` / `PackHandler` / `InstallHandler` / `UninstallHandler` / `ListHandler`）。
+  - Command 层只做：`System.CommandLine` 选项定义、解析、调用 handler。
+
+- Decision: 引入最小抽象层隔离副作用
+  - 抽象接口（实际命名）：
+    - `ICliConsole`：输出/输入、是否交互（替换 `Console.*`）。
+    - `IProcessRunner`：进程执行（替换 `Process.Start`；测试可用 fake runner）。
+  - 默认实现：
+    - `SystemCliConsole`、`ProcessRunner`。
+  - Handler 仅依赖接口；默认实现通过 DI 组装。
+  - 路径隔离：
+    - 测试通过环境变量 `MODULUS_CLI_DATABASE_PATH` / `MODULUS_CLI_MODULES_DIR` 覆盖 CLI 使用的数据库路径与模块目录（由 `CliPathOverrides` 读取）。
+
+- Decision: in-process 测试优先
+  - `Modulus.Cli.IntegrationTests` 默认通过 handler/entrypoint in-process 执行命令。
+  - 仅在必须验证“CLI 打包产物可执行”时，保留少量子进程端到端测试，但不计入覆盖率 gate 的关键路径统计。
+
+## Risks / Trade-offs
+- 风险：重构触发行为漂移（输出/错误码/默认路径）
+  - 缓解：以现有集成测试用例为回归基线；对输出保留关键断言（不做过度字符串耦合）。
+- 风险：抽象层过多导致复杂度上升
+  - 缓解：严格限制接口数量与职责；一类副作用只允许一个抽象入口。
+
+## Migration Plan
+- 先补齐 handler 架构与 DI 基座，再逐个迁移命令（`new`→`build`→`pack`→其余）。
+- 同步迁移测试为 in-process，并以覆盖率报告作为 gate。
+
+## Open Questions
+- 是否需要将 `LocalStorage.GetUserRoot()` 增加可覆盖机制（环境变量/配置）来进一步提升可测试性？
+  - 本变更已通过 CLI 层环境变量覆盖（`MODULUS_CLI_DATABASE_PATH` / `MODULUS_CLI_MODULES_DIR`）满足测试隔离需求，暂不在 Core 层引入额外全局开关。
+
+

openspec/changes/refactor-cli-command-architecture/proposal.md

@@ -0,0 +1,24 @@
+# Change: Refactor CLI Command Architecture for Testability & Coverage
+
+## Why
+当前 `Modulus.Cli` 的部分命令（尤其 `new/build/pack`）以“进程外执行 + `Console`/`Process`/`File` 直连”为主，导致集成测试必须起子进程运行 `modulus.dll`，覆盖率采集无法统计子进程代码，`Modulus.Cli` 覆盖率长期低于预期（当前基线约 13%）。
+
+本变更通过统一的 **Command -> Handler** 架构与可替换依赖抽象，使关键命令可以 **in-process** 执行，从而提升测试稳定性、可诊断性与覆盖率，并为后续 CLI 迭代提供可持续的工程基座。
+
+## What Changes
+- 将 `Modulus.Cli` 所有命令收敛为“薄 Command + 厚 Handler”的结构：Command 负责解析参数与绑定；Handler 负责业务逻辑。
+- 引入最小集合的可替换依赖抽象（`ICliConsole` / `IProcessRunner`），隔离外部副作用，支持测试注入与 deterministic 测试。
+- 调整 `Modulus.Cli.IntegrationTests`：优先使用 **in-process** 执行路径（调用 handler/entrypoint），避免子进程导致覆盖率丢失。
+- 增加覆盖率 gate：`Modulus.Cli\` 关键路径行覆盖率目标 **>= 95%**（不要求覆盖外部工具链自身，如 `dotnet build` 的真实编译行为）。
+ - 为测试与自动化提供路径隔离：通过环境变量 `MODULUS_CLI_DATABASE_PATH` / `MODULUS_CLI_MODULES_DIR` 覆盖 CLI 使用的数据库与模块目录。
+
+## Impact
+- **Affected specs**: `cli-testing` (MODIFIED)
+- **Affected code** (expected):
+  - `src/Modulus.Cli/Program.cs`
+  - `src/Modulus.Cli/Commands/*`
+  - `src/Modulus.Cli/Commands/Handlers/*`
+  - `tests/Modulus.Cli.IntegrationTests/*`
+  - `build/*`（覆盖率采集与汇总脚本/配置）
+
+

openspec/changes/refactor-cli-command-architecture/specs/cli-testing/spec.md

@@ -0,0 +1,40 @@
+## MODIFIED Requirements
+
+### Requirement: CLI Command Tests
+
+CLI 集成测试 SHALL 覆盖所有 CLI 命令的基本功能，并优先使用 in-process 执行路径以确保覆盖率可统计与执行稳定。
+
+#### Scenario: Commands can be executed in-process for coverage
+- **WHEN** 运行 `Modulus.Cli.IntegrationTests`
+- **THEN** `new/build/pack/install/uninstall/list` 的主路径通过 in-process 执行（handler/entrypoint 调用）
+- **AND** 不依赖子进程执行 `modulus.dll` 来覆盖核心逻辑
+
+#### Scenario: Process-based end-to-end tests are allowed but minimal
+- **WHEN** 需要验证 CLI 产物可执行（例如 `modulus.dll` 可被 `dotnet` 启动）
+- **THEN** 允许保留少量进程外端到端测试
+- **AND** 这些测试不作为覆盖率 gate 的主要来源
+
+### Requirement: CLI Test Coverage Gate
+
+关键组件 `Modulus.Cli\` 行覆盖率 MUST 达到 95% 以上。
+
+#### Scenario: Coverage gate fails when below threshold
+- **WHEN** 运行覆盖率汇总脚本（Cobertura）
+- **THEN** 如果 `Modulus.Cli\` 行覆盖率 < 95%
+- **AND** 构建/CI 失败并输出最低覆盖文件列表
+
+### Requirement: CLI Command Handler Architecture
+
+CLI 命令实现 SHALL 采用 “薄 Command + 厚 Handler” 的结构以支持可测试性与依赖注入。
+
+#### Scenario: Command delegates to handler
+- **WHEN** 用户执行任意 CLI 命令（例如 `modulus pack`）
+- **THEN** Command 层仅负责参数解析与调用
+- **AND** 核心业务逻辑位于对应 handler 类中
+
+#### Scenario: Handlers depend on injectable abstractions
+- **WHEN** handler 需要使用 Console/IO/Process 等副作用能力
+- **THEN** handler 通过可注入抽象接口访问这些能力
+- **AND** 测试可替换为 fake 实现以实现 deterministic 行为
+
+

openspec/changes/refactor-cli-command-architecture/tasks.md

@@ -0,0 +1,15 @@
+## 1. Spec
+- [x] 1.1 创建 `refactor-cli-command-architecture` change（proposal/tasks/design）
+- [x] 1.2 增加 `cli-testing` delta spec（MODIFIED requirements）
+- [x] 1.3 `openspec validate refactor-cli-command-architecture --strict` 通过
+
+## 2. Implementation
+- [x] 2.1 增加 CLI 架构基座（handlers + DI 组装 + 抽象接口）
+- [x] 2.2 迁移 `new/build/pack` 到 handler 架构并保持行为不变
+- [x] 2.3 迁移 `install/uninstall/list` 命令入口，使其与 handler 统一（保留现有 handler 能力）
+- [x] 2.4 将 `Modulus.Cli.IntegrationTests` 调整为 in-process 执行主路径（覆盖率可统计）
+- [x] 2.5 补齐单元/集成测试分层与关键用例
+- [x] 2.6 覆盖率 gate：`Modulus.Cli\` 行覆盖率 >= 95%
+- [x] 2.7 全量 `dotnet test Modulus.sln -c Release` 通过
+
+

openspec/specs/cli-testing/spec.md

@@ -21,6 +21,12 @@ CLI 集成测试 SHALL 在隔离环境中运行，不影响真实用户数据。
 - **THEN** CLI 服务使用指定的数据库路径
 - **AND** CLI 服务使用指定的模块目录
 
+#### Scenario: CLI supports path overrides via environment variables
+
+- **WHEN** 设置环境变量 `MODULUS_CLI_DATABASE_PATH` 与 `MODULUS_CLI_MODULES_DIR`
+- **THEN** CLI 使用该数据库路径与模块目录执行 `install/uninstall/list`
+- **AND** 测试可通过设置这些变量实现 in-process 隔离而不写入真实用户目录
+
 ### Requirement: Database Schema Consistency
 
 测试数据库 schema SHALL 与 Host 应用数据库 schema 保持一致。
@@ -34,7 +40,19 @@ CLI 集成测试 SHALL 在隔离环境中运行，不影响真实用户数据。
 
 ### Requirement: CLI Command Tests
 
-CLI 集成测试 SHALL 覆盖所有 CLI 命令的基本功能。
+CLI 集成测试 SHALL 覆盖所有 CLI 命令的基本功能，并优先使用 in-process 执行路径以确保覆盖率可统计与执行稳定。
+
+#### Scenario: Commands can be executed in-process for coverage
+
+- **WHEN** 运行 `Modulus.Cli.IntegrationTests`
+- **THEN** `new/build/pack/install/uninstall/list` 的主路径通过 in-process 执行（handler/entrypoint 调用）
+- **AND** 不依赖子进程执行 `modulus.dll` 来覆盖核心逻辑
+
+#### Scenario: Process-based end-to-end tests are allowed but minimal
+
+- **WHEN** 需要验证 CLI 产物可执行（例如 `modulus.dll` 可被 `dotnet` 启动）
+- **THEN** 允许保留少量进程外端到端测试
+- **AND** 这些测试不作为覆盖率 gate 的主要来源
 
 #### Scenario: New command creates module
 - **WHEN** 执行 `modulus new -n TestModule --force`
@@ -68,6 +86,32 @@ CLI 集成测试 SHALL 覆盖所有 CLI 命令的基本功能。
 - **WHEN** 执行 `modulus list --verbose`
 - **THEN** 额外显示模块 ID、发布者等详细信息
 
+### Requirement: CLI Test Coverage Gate
+
+关键组件 `Modulus.Cli\` 行覆盖率 MUST 达到 95% 以上。
+
+#### Scenario: Coverage gate fails when below threshold
+
+- **WHEN** 运行覆盖率汇总脚本（Cobertura）
+- **THEN** 如果 `Modulus.Cli\` 行覆盖率 < 95%
+- **AND** 构建/CI 失败并输出最低覆盖文件列表
+
+### Requirement: CLI Command Handler Architecture
+
+CLI 命令实现 SHALL 采用 “薄 Command + 厚 Handler” 的结构以支持可测试性与依赖注入。
+
+#### Scenario: Command delegates to handler
+
+- **WHEN** 用户执行任意 CLI 命令（例如 `modulus pack`）
+- **THEN** Command 层仅负责参数解析与调用
+- **AND** 核心业务逻辑位于对应 handler 类中
+
+#### Scenario: Handlers depend on injectable abstractions
+
+- **WHEN** handler 需要使用 Console/Process 等副作用能力
+- **THEN** handler 通过可注入抽象接口访问这些能力（例如 `ICliConsole`, `IProcessRunner`）
+- **AND** 测试可替换为 fake 实现以实现 deterministic 行为
+
 ### Requirement: Module Load Verification
 
 CLI 集成测试 SHALL 验证生成的模块能被 `ModuleLoader` 正确加载。