Refactor modulus new to template-based syntax

BREAKING: remove legacy new options; add --list and default module-avalonia; update tests/docs/specs

Author: Hongwei-MB

README.md

@@ -72,7 +72,7 @@ dotnet new install Agibuild.Modulus.Templates
 
 ```bash
 # Create a new module
-modulus new MyModule -t avalonia
+modulus new -n MyModule
 
 # Or use dotnet new
 dotnet new modulus-avalonia -n MyModule
@@ -108,7 +108,7 @@ Modulus provides a comprehensive command-line tool for module development and ma
 
 | Command | Description |
 |---------|-------------|
-| `modulus new <name>` | Create a new module project |
+| `modulus new` | Create a new module project |
 | `modulus build` | Build the module in current directory |
 | `modulus pack` | Build and package as .modpkg |
 | `modulus install <source>` | Install a module |
@@ -118,13 +118,11 @@ Modulus provides a comprehensive command-line tool for module development and ma
 ### Create Module
 
 ```bash
-modulus new MyModule [options]
+modulus new [<template>] -n MyModule [options]
 
 Options:
-  -t, --target <avalonia|blazor>  Target host platform
-  -d, --display-name <name>       Display name in menus
-  -p, --publisher <name>          Publisher name
-  -i, --icon <icon>               Menu icon
+  -n, --name <name>               Module name (PascalCase)
+  -o, --output <dir>              Output directory
   --force                         Overwrite existing
 ```
 
@@ -165,7 +163,7 @@ modulus list --verbose
 ### 1. Create Projects
 
 ```bash
-modulus new MyExtension -t avalonia
+modulus new -n MyExtension
 ```
 
 This creates:

README.zh-CN.md

@@ -72,7 +72,7 @@ dotnet new install Agibuild.Modulus.Templates
 
 ```bash
 # 创建新模块
-modulus new MyModule -t avalonia
+modulus new -n MyModule
 
 # 或使用 dotnet new
 dotnet new modulus-avalonia -n MyModule
@@ -108,7 +108,7 @@ Modulus 提供全面的命令行工具用于模块开发和管理。
 
 | 命令 | 描述 |
 |------|------|
-| `modulus new <name>` | 创建新模块项目 |
+| `modulus new` | 创建新模块项目 |
 | `modulus build` | 在当前目录编译模块 |
 | `modulus pack` | 编译并打包为 .modpkg |
 | `modulus install <source>` | 安装模块 |
@@ -118,13 +118,11 @@ Modulus 提供全面的命令行工具用于模块开发和管理。
 ### 创建模块
 
 ```bash
-modulus new MyModule [options]
+modulus new [<template>] -n MyModule [options]
 
 选项:
-  -t, --target <avalonia|blazor>  目标主机平台
-  -d, --display-name <name>       菜单中显示的名称
-  -p, --publisher <name>          发布者名称
-  -i, --icon <icon>               菜单图标
+  -n, --name <name>               模块名称 (PascalCase)
+  -o, --output <dir>              输出目录
   --force                         覆盖已有文件
 ```
 
@@ -165,7 +163,7 @@ modulus list --verbose
 ### 1. 创建项目
 
 ```bash
-modulus new MyExtension -t avalonia
+modulus new -n MyExtension
 ```
 
 这将创建：

build/BuildTasks.cs

@@ -851,7 +851,7 @@ private static bool IsSharedAssembly(string fileName)
             LogNormal("");
             LogNormal("To use these packages in module templates:");
             LogNormal("  1. Run 'nuke add-local-source' (if not done)");
-            LogNormal("  2. Run 'modulus new MyModule --target avalonia'");
+            LogNormal("  2. Run 'modulus new -n MyModule'");
             LogNormal("  3. dotnet restore will find packages from local source");
         });
 

docs/cli-reference.md

@@ -35,48 +35,43 @@ Create a new Modulus module project with all necessary files and structure.
 ### Syntax
 
 ```bash
-modulus new <name> [options]
+modulus new [<template>] -n <name> [options]
 ```
 
 ### Arguments
 
 | Argument | Required | Description |
 |----------|----------|-------------|
-| `<name>` | Yes | The module name (used for project and namespace) |
+| `<template>` | No | Template name: `module-avalonia` or `module-blazor` (default: `module-avalonia`) |
 
 ### Options
 
 | Option | Short | Description | Default |
 |--------|-------|-------------|---------|
-| `--target` | `-t` | Target host: `avalonia` or `blazor` | (interactive) |
-| `--display-name` | `-d` | Display name shown in menus | Same as name |
-| `--description` | | Module description | Generated |
-| `--publisher` | `-p` | Publisher name | (interactive) |
-| `--icon` | `-i` | Menu icon (IconKind value) | `Folder` |
-| `--order` | `-o` | Menu order | `100` |
-| `--output` | | Output directory | Current directory |
+| `--name` | `-n` | The module name (used for project and namespace) | (required) |
+| `--output` | `-o` | Output directory | Current directory |
 | `--force` | `-f` | Overwrite existing directory | `false` |
+| `--list` | | List available templates and exit | `false` |
 
-### Available Icons
+### Templates
 
-Common icon values: `Folder`, `Home`, `Settings`, `Terminal`, `Code`, `Database`, `Cloud`, `User`, `Star`, `Heart`, `Search`, `Edit`, `Delete`, `Add`, `Check`, `Close`, `Info`, `Warning`, `Error`
-
-See the full list in `Modulus.UI.Abstractions.IconKind` enum.
+- `module-avalonia`: Modulus module (Avalonia)
+- `module-blazor`: Modulus module (Blazor)
 
 ### Examples
 
 ```bash
-# Interactive mode (prompts for all options)
-modulus new MyModule
+# List templates
+modulus new --list
 
-# Create Avalonia module with all options
-modulus new MyModule -t avalonia -d "My Module" -p "Acme Corp" -i Home
+# Create an Avalonia module (default template)
+modulus new -n MyModule
 
-# Create Blazor module in specific directory
-modulus new MyModule -t blazor --output ./src/Modules/
+# Create a Blazor module in a specific directory
+modulus new module-blazor -n MyModule -o ./src/Modules/
 
 # Overwrite existing project
-modulus new MyModule -t avalonia --force
+modulus new -n MyModule --force
 ```
 
 ### Generated Structure

docs/getting-started.md

@@ -60,7 +60,7 @@ dotnet run --project src/Hosts/Modulus.Host.Avalonia
 Using the CLI:
 
 ```bash
-modulus new MyFirstModule -t avalonia
+modulus new -n MyFirstModule
 cd MyFirstModule
 ```
 

docs/getting-started.zh-CN.md

@@ -60,7 +60,7 @@ dotnet run --project src/Hosts/Modulus.Host.Avalonia
 使用 CLI：
 
 ```bash
-modulus new MyFirstModule -t avalonia
+modulus new -n MyFirstModule
 cd MyFirstModule
 ```
 

docs/samples/home-mockup-orbital.html

@@ -557,7 +557,7 @@ <h3>AI Agent 就绪</h3>
                 </div>
                 <div class="cli-line">
                     <span class="cli-prompt">$</span>
-                    <span class="cli-command">modulus new <span class="cli-highlight">MyModule</span> -t avalonia</span>
+                    <span class="cli-command">modulus new -n <span class="cli-highlight">MyModule</span></span>
                     <span class="cli-comment"># 创建新模块</span>
                 </div>
                 <div class="cli-line">

openspec/changes/archive/2025-12-17-refactor-modulus-new-command/design.md

@@ -0,0 +1,55 @@
+## Context
+
+本变更聚焦于 `modulus new` 的命令行体验，目标是收敛参数面并对齐 `dotnet new` 的使用模型：以 template 选择为主、以通用参数（name/output/force）为辅，避免将模板内部元数据暴露为 CLI 参数。
+
+## Goals / Non-Goals
+
+- Goals
+  - 最小参数面：创建项目只需理解 template + name + output/force
+  - 具备可发现性：支持 `modulus new --list` 列出模板
+  - 默认行为明确：未指定 template 时默认 `module-avalonia`
+  - 立即删除冗余参数（breaking change）
+- Non-Goals
+  - 不在本变更中引入更多模板（仅 `module-avalonia`/`module-blazor`）
+  - 不在本变更中更改生成的文件内容语义（仅命令行入口与参数映射调整）
+
+## Decisions
+
+### Decision: New syntax
+
+Primary syntax:
+
+```bash
+modulus new [<template>] -n <name> [-o <dir>] [-f] [--list]
+```
+
+- `<template>`: `module-avalonia` / `module-blazor`（可选；缺省时为 `module-avalonia`）
+- `-n|--name`: 模块名（PascalCase）
+- `-o|--output`: 输出目录（默认当前目录）
+- `-f|--force`: 覆盖已有目录
+- `--list`: 列出模板并退出（不创建项目）
+
+### Decision: Immediate removal of legacy options
+
+Deleted options (no compatibility layer):
+- `--target/-t`
+- `--display-name/-d`
+- `--description`
+- `--publisher/-p`
+- `--icon/-i`
+- `--order/-o`
+
+Rationale: 这些参数属于模板内部元数据，应该由生成后修改文件/代码来完成，而不是创建命令的必选理解成本。
+
+## Risks / Trade-offs
+
+- **BREAKING**：脚本/文档中旧语法会失败，需要同步更新测试与文档。
+- 模板元数据不可在创建时通过 CLI 注入，用户需改生成文件（但换来更稳定的命令面）。
+
+## Migration Plan
+
+- Update docs/examples and integration tests to:
+  - `modulus new -n MyModule`（默认 `module-avalonia`）
+  - `modulus new module-blazor -n MyModule`
+
+

openspec/changes/archive/2025-12-17-refactor-modulus-new-command/proposal.md

@@ -0,0 +1,31 @@
+# Change: Refactor `modulus new` command surface to dotnet-new style
+
+## Why
+
+当前 `modulus new` 将大量模板元数据（显示名称、发布者、图标、菜单顺序等）暴露为命令行参数，导致参数面过大、难以发现与难以脚本化，也与 `dotnet new` 的最佳实践不一致。
+
+## What Changes
+
+- 将 `modulus new` 重构为 **dotnet-new 风格**：
+  - 以 **template** 驱动创建：`modulus new [<template>] -n <name> ...`
+  - 提供 `--list` 列出可用模板
+  - 未显式指定模板时，默认使用 `module-avalonia`
+- **BREAKING**：移除不必要的参数（立即删除，不做兼容别名/隐藏参数）
+  - 移除：`--target/-t`、`--display-name/-d`、`--description`、`--publisher/-p`、`--icon/-i`、`--order/-o`
+- 统一创建命令的通用参数与语义
+  - `-n|--name`：模块名（PascalCase）
+  - `-o|--output`：输出目录（默认当前目录）
+  - `-f|--force`：覆盖已有目录
+
+## Impact
+
+- Affected specs:
+  - `openspec/specs/module-template/spec.md`（CLI 命令语法与行为）
+  - `openspec/specs/cli-testing/spec.md`（new 命令测试用例语法）
+- Affected code (expected):
+  - `src/Modulus.Cli/Commands/NewCommand.cs`（参数定义、解析与行为）
+  - `tests/Modulus.Cli.IntegrationTests/Infrastructure/CliRunner.cs`
+  - `tests/Modulus.Cli.IntegrationTests/Commands/NewCommandTests.cs`
+  - `docs/cli-reference.md`、`docs/getting-started*.md`、`README*.md`（命令示例）
+
+

openspec/changes/archive/2025-12-17-refactor-modulus-new-command/specs/cli-testing/spec.md

@@ -0,0 +1,41 @@
+# cli-testing Specification (Delta)
+
+## MODIFIED Requirements
+
+### Requirement: CLI Command Tests
+
+CLI 集成测试 SHALL 覆盖所有 CLI 命令的基本功能。
+
+#### Scenario: New command creates module
+- **WHEN** 执行 `modulus new -n TestModule --force`
+- **THEN** 创建包含正确结构的模块目录
+- **AND** 生成 `.sln`、`.csproj`、`extension.vsixmanifest` 等文件
+
+#### Scenario: Build command compiles module
+- **WHEN** 在模块目录执行 `modulus build`
+- **THEN** 编译成功并生成 DLL 文件
+- **AND** 返回退出码 0
+
+#### Scenario: Pack command creates package
+- **WHEN** 在模块目录执行 `modulus pack`
+- **THEN** 生成 `.modpkg` 文件
+- **AND** 包内包含 `extension.vsixmanifest` 和模块 DLL
+
+#### Scenario: Install command registers module
+- **WHEN** 执行 `modulus install <path>.modpkg`
+- **THEN** 解压包到模块目录
+- **AND** 在数据库中注册模块
+- **AND** `modulus list` 显示已安装模块
+
+#### Scenario: Uninstall command removes module
+- **WHEN** 执行 `modulus uninstall <name> --force`
+- **THEN** 从数据库中删除模块记录
+- **AND** `modulus list` 不再显示该模块
+
+#### Scenario: List command shows installed modules
+- **WHEN** 已安装模块后执行 `modulus list`
+- **THEN** 显示模块名称和版本
+- **WHEN** 执行 `modulus list --verbose`
+- **THEN** 额外显示模块 ID、发布者等详细信息
+
+