flu-cli 2.0.5 → 2.1.0

package/scripts/smoke-vnext-params.mjs

@@ -0,0 +1,92 @@
+import { buildVNextProjectOptions } from '../lib/commands/vnext-options.js'
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message)
+  }
+}
+
+const options = buildVNextProjectOptions({
+  auth: true,
+  helpers: 'payment,webview,permission,imagePicker',
+  examples: 'commonListHome,networkRequest,networkGallery',
+  platforms: 'android,ios,harmony',
+  architectureMode: 'native',
+  compositionProfile: 'base_mixins',
+  enableMixinOptions: 'true',
+  serialization: 'freezed',
+  flutterSdk: 'custom',
+  flutterBin: '/opt/flutter/bin/flutter',
+})
+
+assert(options.capabilities.auth.enabled === true, 'auth should enable auth capability')
+assert(options.capabilities.serialization.enabled === true, 'serialization should be enabled')
+assert(options.capabilities.serialization.strategy === 'freezed', 'serialization strategy mismatch')
+assert(
+  options.capabilities.serialization.buildRunner === true,
+  'freezed serialization should enable build_runner',
+)
+assert(options.helpers.payment === true, 'payment helper should be enabled')
+assert(options.helpers.webview === true, 'webview helper should be enabled')
+assert(options.helpers.permission === true, 'permission helper should be enabled')
+assert(options.helpers.imagePicker === true, 'imagePicker helper should be enabled')
+assert(
+  options.examples.join(',') === 'networkGallery',
+  'default list example should be ignored and network request alias should normalize to gallery',
+)
+assert(options.architectureMode === 'native', 'architecture mode should normalize to native')
+assert(options.enableMixinOptions === true, 'enableMixinOptions should normalize to true')
+assert(
+  options.composition.profile === 'base_mixins',
+  'composition profile should preserve base_mixins',
+)
+assert(
+  options.composition.architectureMode === 'native',
+  'composition architecture mode should be preserved',
+)
+assert(
+  options.composition.enableMixinOptions === true,
+  'composition mixin option flag should be preserved',
+)
+assert(options.platforms.join(',') === 'android,ios,harmony', 'platforms should preserve CLI order')
+assert(options.flutterSdk.mode === 'custom', 'flutter SDK mode mismatch')
+assert(options.flutterSdk.flutterBin === '/opt/flutter/bin/flutter', 'custom flutter bin mismatch')
+
+const fvmOptions = buildVNextProjectOptions({
+  helpers: 'image-picker',
+  examples: 'gallery,request,webview,permission,image-picker,payment',
+  platforms: 'harmonyos',
+  compositionProfile: 'pure_mixins',
+  serialization: 'manual',
+  flutterSdk: 'fvm',
+  flutterSdkVersion: '3.22.0',
+})
+
+assert(fvmOptions.helpers.imagePicker === true, 'image-picker alias should map to imagePicker')
+assert(
+  fvmOptions.examples.join(',') ===
+    'networkGallery,webviewBasic,permissionBasic,imagePickerBasic,paymentShell',
+  'example aliases should normalize to official example ids',
+)
+assert(fvmOptions.platforms[0] === 'harmony', 'harmonyos should normalize to harmony')
+assert(fvmOptions.flutterSdk.mode === 'fvm', 'fvm Flutter SDK mode mismatch')
+assert(fvmOptions.flutterSdk.version === '3.22.0', 'fvm Flutter SDK version mismatch')
+assert(
+  fvmOptions.architectureMode === 'native',
+  'pure profile should default architecture mode to native',
+)
+assert(
+  fvmOptions.enableMixinOptions === true,
+  'pure_mixins should default enableMixinOptions to true',
+)
+assert(fvmOptions.composition.profile === 'pure', 'pure_mixins should normalize to pure profile')
+assert(
+  fvmOptions.capabilities.serialization.enabled === true,
+  'manual serialization should be enabled',
+)
+assert(
+  fvmOptions.capabilities.serialization.buildRunner === false,
+  'manual serialization should not enable build_runner',
+)
+
+console.log('cli vNext params smoke: ok')

package/CLI.md

@@ -1,513 +0,0 @@
-# Flu-CLI v2 命令参考
-
-> Flutter MVVM 脚手架工具 - 快速生成项目和代码
-
-## 快速开始
-
-```bash
-# 创建新项目
-flu-cli new my_app
-
-# 添加页面
-flu-cli add page home
-
-# 查看帮助
-flu-cli --help
-```
-
-## 新增特性（v2）
-
--   自定义模板管理：支持从本地目录或 Git 仓库添加模板，并在交互式创建时与内置模板一起选择。
--   项目生成配置：支持在项目根使用 `.flu-cli.json` 配置生成器默认行为（路径、页面类型、是否绑定 ViewModel 等）。
--   生成联动：CLI 与 VSCode 扩展均会读取 `.flu-cli.json`，保持生成路径与风格一致。
--   Riverpod 原生支持：可选择 Riverpod 状态管理并生成原生风格的 VM/页面（如果模板包含入口片段会自动包裹 `ProviderScope`）。
-
-## 命令列表
-
-### 1. `new` - 创建项目
-
-创建一个新的 Flutter 项目，支持多种模板和状态管理器。
-
-**选项:**
-
-```bash
-flu-cli new [项目名称] [选项]
-flu-cli n [项目名称]  # 简写
-```
-
-**选项:**
-
--   `-t, --template <type>` - 模板类型: `lite`, `modular`, `clean`
--   `-s, --state <type>` - 状态管理器: `default`, `provider`, `getx`, `riverpod`
--   `-d, --dir <path>` - 项目存放目录（默认：当前目录）
--   `--no-cache` - 不使用缓存，强制从 Git 拉取
--   `--no-network` - 不包含网络层（默认包含）
--   `--remote` - 使用远程 Gitee 模板（默认使用本地模板）
-
-**说明:**
-
--   交互式创建时会展示“内置模板 + 你通过 `template add` 保存的自定义模板”，可直接选择。
--   模板复制后会执行占位符替换（如 `{{projectName}}`、`{{package_name}}`）并校正 `pubspec.yaml` 的 `name`。
--   已存在 `.flu-cli.json` 的项目中再次生成文件时，会遵循其中的路径与风格设置。
-
-**示例:**
-
-```bash
-# 交互式创建（推荐）
-flu-cli new
-
-# 指定项目名和模板
-flu-cli new my_app -t lite
-
-# 指定状态管理器
-flu-cli new my_app -s getx
-
-# 完整配置
-flu-cli new my_app -t modular -s provider -d ~/projects
-```
-
----
-
-### 2. `add` - 添加组件
-
-在当前项目中添加各种代码组件。
-
-**用法:**
-
-```bash
-flu-cli add <类型> <名称> [选项]
-flu-cli a <类型> <名称>  # 简写
-```
-
-**支持的类型及别名:**
-
-| 类型        | 别名  | 说明         |
-| ----------- | ----- | ------------ |
-| `page`      | `p`   | 页面组件     |
-| `widget`    | `w`   | 通用组件     |
-| `component` | `c`   | 业务组件     |
-| `viewmodel` | `v`   | ViewModel    |
-| `service`   | `s`   | 服务层       |
-| `model`     | `m`   | 数据模型     |
-| `module`    | `mod` | 完整功能模块 |
-
-**选项:**
-
--   `-f, --feature <name>` - 所属功能模块（仅 modular/clean 模式）
--   `--stateful` - 创建 StatefulWidget
--   `--stateless` - 强制创建 StatelessWidget
--   `--list-page` - 创建列表页 (BaseListPage)
--   `--no-vm` - 不生成 ViewModel（仅 page 类型）
--   `--type <type>` - Service 类型: `api`, `storage`, `auth`（仅 service 类型）
--   `--json <file>` - 从 JSON 文件生成（仅 model 类型）
--   `--list` - 查看支持的类型列表
-
-**说明:**
-
--   若项目根存在 `.flu-cli.json`，`add` 会遵循其中的路径与默认类型（如 `generators.page.path`、`defaultType`、`withViewModel`）。
--   在 `modular/clean` 模板下可用 `-f <feature>` 指定模块以生成到模块目录结构（如 `lib/features/user/...`）。
-
-**示例:**
-
-```bash
-# 添加页面（自动生成 ViewModel）
-flu-cli add page home
-flu-cli add p home  # 简写
-
-# 添加列表页
-flu-cli add page user_list --list-page
-
-# 添加无状态页面
-flu-cli add page about --stateless --no-vm
-
-# 添加组件
-flu-cli add widget custom_button
-flu-cli add w custom_button  # 简写
-
-# 添加 Service
-flu-cli add service api --type api
-flu-cli add s auth --type auth  # 简写 + 指定类型
-
-# 添加 Model
-flu-cli add model user
-flu-cli add m user  # 简写
-
-# 在功能模块下添加（modular/clean 模式）
-flu-cli add page product -f shop
-```
-
-### 2.5 `service` - 服务层
-
-生成 API、存储等服务。
-
-**选项:**
-
--   `-f, --feature <name>` - 指定功能模块
--   `--type <type>` - 服务类型: api, storage, auth (默认: api) [**已废弃**: 默认生成基础 Service 结构]
-
-**示例:**
-
-```bash
-# 生成 User 服务
-flu-cli add service user
-
-# 在 auth 模块中生成 AuthService
-flu-cli add service auth --feature auth
-```
-
----
-
-### 3. `templates` - 模板管理
-
-查看可用模板列表或指定模板的详细信息。
-
-**用法:**
-
-```bash
-flu-cli templates [模板名称]
-flu-cli t [模板名称]  # 简写
-```
-
-**示例:**
-
-```bash
-# 查看所有模板
-flu-cli templates
-
-# 查看指定模板详情
-flu-cli templates lite
-flu-cli t modular  # 简写
-```
-
----
-
-### 9. `template` - 自定义模板管理（新增）
-
-用于管理你自己的项目模板，支持从本地目录或 Git 仓库新增模板，并持久化到 `~/.flu-cli/config.json`。在交互式创建项目时，这些模板会与内置模板一起展示并可直接选择。
-
-**用法:**
-
-```bash
-flu-cli template                # 查看所有自定义模板（同 list）
-flu-cli template list           # 列出所有模板
-flu-cli template add <id> <source> [选项]
-flu-cli template remove <id>
-```
-
-**选项:**
-
--   `--local` 使用本地目录作为模板（`source` 为路径）
--   `-n, --name <name>` 显示名称（可选）
--   `-b, --branch <branch>` Git 模板分支（默认 `main`）
--   `-d, --description <text>` 模板描述
--   `-f, --force` 覆盖已存在的同名模板
-
-**示例:**
-
-```bash
-# 添加本地模板
-flu-cli template add my-lite /path/to/my-template --local -n "我的 Lite 模板" -d "带业务框架的轻量模板"
-
-# 添加 Git 模板
-flu-cli template add company-clean https://github.com/org/clean-template.git -b main -n "公司 Clean 模板"
-
-# 列出/移除模板
-flu-cli template list
-flu-cli template remove my-lite
-```
-
-**说明:**
-
--   模板会缓存到 `~/.flu-cli/templates/<id>/`，创建项目时会从缓存复制。
--   交互式 `flu-cli new` 会把自定义模板和内置模板一起展示，并支持预览说明。
--   选择 Git 模板时会从远端克隆到缓存目录；选择本地模板时会直接复制到缓存目录。
-
----
-
-### 10. `config` - 项目生成配置（新增）
-
-初始化并管理项目根目录下的 `.flu-cli.json`，用于声明生成器的默认行为（路径、页面类型、是否绑定 ViewModel 等）。VSCode 扩展与 v2 的生成命令都会读取该文件。
-
-**用法:**
-
-```bash
-flu-cli config init [选项]
-```
-
-**选项:**
-
--   `-d, --dir <path>` 目标项目目录（默认当前目录）
--   `-f, --force` 覆盖已存在的配置文件
-
-**示例:**
-
-```bash
-# 在当前项目生成配置
-flu-cli config init
-
-# 指定项目目录并覆盖旧配置
-flu-cli config init -d ~/projects/my_app -f
-```
-
-**.flu-cli.json 示例（简化）:**
-
-```json
-{
-    "generators": {
-        "page": {
-            "path": "lib/pages",
-            "defaultType": "stateful",
-            "withViewModel": true
-        },
-        "viewModel": {
-            "path": "lib/viewmodels"
-        },
-        "model": {
-            "path": "lib/models"
-        }
-    }
-}
-```
-
-**说明:**
-
--   初始化时会根据项目模板（lite/modular/clean）生成匹配的默认路径。
--   VSCode 插件的“生成文件”命令会优先使用 `.flu-cli.json` 中的设置，无需每次选择类型。
--   可在自定义模板中提供示例 `.flu-cli.json`，在创建后运行 `flu-cli config init -f` 以覆盖为团队约定。
-
----
-
-### 5. `update-templates` - 更新模板缓存
-
-更新本地模板缓存到最新版本。
-
-**用法:**
-
-```bash
-flu-cli update-templates [模板名称]
-flu-cli u [模板名称]  # 简写
-```
-
-**选项:**
-
--   `--force` - 强制刷新并清理未跟踪文件
-
-**示例:**
-
-```bash
-# 更新所有模板
-flu-cli update-templates
-
-# 更新指定模板
-flu-cli u lite  # 简写
-
-# 强制刷新
-flu-cli update-templates --force
-```
-
----
-
-### 6. `cache` - 缓存管理
-
-管理本地模板缓存。
-
-**用法:**
-
-```bash
-flu-cli cache <action>
-flu-cli c <action>  # 简写
-```
-
-**支持的操作:**
-
--   `clean` - 清理缓存
-
-**示例:**
-
-```bash
-# 清理缓存
-flu-cli cache clean
-flu-cli c clean  # 简写
-```
-
----
-
-### 7. `completion` - 自动补全
-
-生成 Shell 自动补全脚本（支持 Bash/Zsh）。
-
-**用法:**
-
-```bash
-flu-cli completion
-flu-cli comp  # 简写
-```
-
-**安装方法:**
-
-```bash
-# Zsh
-flu-cli completion >> ~/.zshrc
-source ~/.zshrc
-
-# Bash
-flu-cli completion >> ~/.bashrc
-source ~/.bashrc
-```
-
----
-
-## 常见问题 (FAQ)
-
-**Q: `add page` 默认生成的代码不符合我的项目结构怎么办？**
-
-A: Flu CLI 是为特定架构（MVVM + Provider）设计的。如果您使用完全自定义的架构，建议：
-
-1. 使用 `--no-vm` 仅生成页面。
-2. 或者，Fork 本项目并修改模板代码以适配您的团队规范。
-3. 利用 VSCode 插件自带的代码片段 (Snippets) 快速编写代码，而不是依赖 CLI 生成。
-
-**Q: 为什么生成的 Service 很简单？**
-
-A: 我们移除了原来复杂的 Service 模板，只生成最基础的类结构。这样您可以自由选择使用 `http`, `dio` 还是其他网络库，而不受 CLI 预设逻辑的限制。
-
----
-
-## 常见工作流
-
-### 创建新项目
-
-```bash
-flu-cli new my_app
-cd my_app
-flutter pub get
-flu-cli add page home
-flu-cli add page user_list --list-page
-```
-
-### 使用自定义模板创建项目
-
-````bash
-# 添加模板（本地或 Git）
-flu-cli template add my-lite /path/to/my-template --local
-# 或
-flu-cli template add company-clean https://github.com/org/clean-template.git -b main
-
-# 交互式选择自定义模板并创建
-flu-cli new
-
-# 初始化项目生成配置（让 VSCode/CLI 生成遵循你的路径约定）
-flu-cli config init
-
-### 基于配置快速生成页面/VM
-```bash
-# 初始化配置后：
-flu-cli add page home            # 路径/类型按 .flu-cli.json 生效
-flu-cli add viewmodel home       # VM 路径按配置生效
-flu-cli add model user           # Model 路径按配置生效
-````
-
-### 更新模板缓存与故障排除
-
-```bash
-# 更新缓存到最新
-flu-cli update-templates [模板ID]
-
-# 模板拉取失败或缓存异常
-flu-cli cache clean
-flu-cli new my_app --no-cache
-```
-
-````
-
-### 在现有项目中使用
-
-```bash
-cd existing_project
-
-# 初始化配置文件
-flu-cli config init
-
-# 添加组件
-flu-cli add page settings
-flu-cli add service api
-````
-
-### Modular 架构项目
-
-```bash
-flu-cli new my_app -t modular
-cd my_app
-
-# 在 shop 模块下添加页面
-flu-cli add page product -f shop
-flu-cli add page cart -f shop
-
-# 在 user 模块下添加页面
-flu-cli add page profile -f user
-```
-
----
-
-## 全局选项
-
-所有命令都支持以下选项：
-
--   `-V, --version` - 查看版本号
--   `-h, --help` - 查看帮助信息
-
-**示例:**
-
-```bash
-flu-cli --version
-flu-cli add --help
-```
-
----
-
-## 配置文件
-
-Flu-CLI 会在以下位置存储配置：
-
--   **缓存目录**: `~/.flu-cli/cache/`
--   **配置文件**: `~/.flu-cli/config.json`
-
----
-
-## 故障排除
-
-### 命令卡住
-
-如果命令执行过程中卡住，可以：
-
-1. 按 `Ctrl+C` 中止
-2. 运行 `flu-cli cache clean` 清理缓存
-3. 重新执行命令
-
-### 模板拉取失败
-
-```bash
-# 清理缓存后重试
-flu-cli cache clean
-flu-cli new my_app
-
-# 或使用本地模板（开发环境）
-flu-cli new my_app --no-cache
-```
-
-### 代码片段不生效
-
-VSCode 扩展使用**动态代码片段**功能，会根据项目配置自动适配：
-
-1. 确保已安装 Flu CLI VSCode 扩展
-2. 打开 `.dart` 文件时扩展会自动激活
-3. 代码片段会根据 `.flu-cli.json` 配置动态显示
-4. 如果看不到代码片段，尝试重启 VSCode
-
----
-
-## 更多帮助
-
--   查看具体命令帮助：`flu-cli <command> --help`
--   项目文档：[flu-cli 文档站](https://your-docs-url)
--   问题反馈：[GitHub Issues](https://github.com/your-repo/issues)