@dao-style/cli

# @dao-style/cli DAO Style 项目的命令行工具 - 提供项目脚手架、模板生成和依赖管理功能。 ## 🚀 Features - **NPM Template System**: 使用 `@dao-style-template/` 组织下的 npm 包作为模板 - **Version Management**: 模板版本自动写入 `devDependencies`，支持版本追踪 - **Smart Upgrade**: 检测可升级的模板版本，支持三方合并和冲突解决 - **Post-install Tasks**: 自动执行模板的安装后任务 - **Template Cache**: 智能缓存下载的模板，提升性能 ## 前置要求 - Node.js >= 20.0.0 - pnpm >= 9.0.0 ## 安装 ```bash npm install -g @dao-style/cli 或 pnpm add -g @dao-style/cli ``` ## 📦 Template System ### NPM Templates 项目使用 `@dao-style-template/` 组织下的 npm 包作为模板： - `@dao-style-template/base` - 基础项目结构 - `@dao-style-template/lint` - ESLint 和代码格式化配置 - `@dao-style-template/ci` - CI/CD 配置 ### Version Management 模板的具体版本会自动写入项目的 `devDependencies`： ```json { "devDependencies": { "@dao-style-template/base": "1.0.0", "@dao-style-template/lint": "1.2.0", "@dao-style-template/ci": "1.1.0" } } ``` ## 🛠️ Commands ### 创建新项目 `project-name` 为项目名称，无需包含 `ui` ，`ui` 会根据项目名称自动生成。 ```bash dao create <project-name> [options] ``` #### 基础用法 ```bash dao create my-app ``` 创建新项目，自动： - 下载最新版本的模板 - 生成项目文件 - 将模板版本写入 `devDependencies` - 设置 postinstall 钩子 #### 可选参数 | 参数 | 简写 | 说明 | 默认值 | | --------------------------- | ---- | ------------------------------------------------------------- | -------- | | `--initial-branch <branch>` | `-b` | 设置初始分支名称 | `master` | | `--local` | - | 使用本地模板（开发调试用） | - | | `--all-templates` | - | 选择所有可用模板 | - | | `--answer <templatePrompt>` | - | 提供模板提示的答案，格式：`template.prompt=value`，可重复使用 | - | #### 高级用法示例 **1. 使用所有模板并预设答案** ```bash dao create test --all-templates \ --answer base.packages=@dao-style/core,@dao-style/extend,@dao-style/biz \ --answer base.port=8100 ``` 这个命令会： - 创建名为 `test` 的项目 - 应用所有可用的模板 - 预设 base 模板的 `packages` 参数为 `@dao-style/core,@dao-style/extend,@dao-style/biz` - 预设 base 模板的 `port` 参数为 `8100` **2. 自定义初始分支** ```bash dao create my-app --initial-branch main ``` **3. 使用本地模板（开发调试）** ```bash dao create test-project --local ``` ### 查看模板状态 ```bash dao list ``` 查看当前项目安装的模板版本和可用更新： ``` 📦 Installed Templates: base: 1.0.0 → 1.2.0 (update available) lint: 1.1.0 (up to date) ci: 1.0.0 → 1.1.0 (update available) 💡 Run "dao upgrade" to update templates. ``` ### 升级模板 ```bash dao upgrade [options] ``` 升级项目中的模板到最新版本，支持智能三方合并和冲突解决。 #### 可选参数 | 参数 | 说明 | 默认值 | | --------- | -------------------------- | ------ | | `--local` | 使用本地模板（开发调试用） | - | #### 基础用法 ```bash dao upgrade ``` 该命令会： 1. **检查 Git 状态** - 确保工作目录干净（可用 `--force` 跳过） 2. **检测可用更新** - 扫描所有已安装模板的新版本 3. **选择升级模板** - 交互式选择要升级的模板 4. **处理模板提示** - 智能判断是否需要重新回答 prompts 5. **执行三方合并** - 自动合并文件变更 6. **解决冲突** - 自动或手动解决冲突 7. **更新依赖** - 更新 `package.json` 并执行 `pnpm install` ### ⚠️ 升级注意事项 #### 升级前的建议 1. **提交所有更改** - 升级前确保所有代码已提交到 Git 2. **创建备份分支** - 建议创建备份分支： `git checkout -b backup-before-upgrade` 3. **了解变更内容** - 使用 `dao list` 查看可用更新 4. **测试升级结果** - 升级后运行测试确保功能正常 #### 升级后的操作 1. **解决冲突** - 如果有冲突，先解决所有冲突标记 2. **运行开发服务器** - `pnpm serve` 确保项目能正常启动 3. **执行 Lint 检查** - `pnpm lint` 确保代码规范 4. **运行测试** - `pnpm test:unit` 确保功能正常 5. **提交更改** - `git add .` 和 `git commit -m "chore: upgrade templates"` #### 升级流程示例 ```bash $ dao upgrade # 1. 检查 Git 状态 ✓ Working directory is clean # 2. 检测可用更新 📦 Available updates: - base: 1.0.0 → 1.2.0 (update available) - lint: 1.1.0 → 1.3.0 (update available) - ci: 1.0.0 (up to date) # 3. 选择要升级的模板 ? Select templates to upgrade: ◉ base Template (1.0.0 → 1.2.0) ◉ lint Template (1.1.0 → 1.3.0) ◯ ci Template (up to date) # 4. 处理 prompts（如果模板 prompts 有变化） Processing base prompts... ? Select packages: @dao-style/core, @dao-style/extend ? Port number: 8100 # 5. 执行升级 ✓ Updated: src/main.ts ✓ Merged: vite.config.ts ⚠ Merged with conflicts: .eslintrc.js ✓ Added: src/types/global.d.ts ✓ Deleted: old-config.js # 6. 更新 package.json ✓ Updated: package.json # 7. 安装依赖 ✓ Dependencies installed # 如果有冲突 ⚠ Upgrade completed with conflicts in the below files. Please resolve them and commit the changes: - .eslintrc.js Opening conflicts in VS Code... ``` ## 🔄 升级机制详解 ### Prompt 智能处理升级时会智能判断是否需要重新回答 prompts： #### 场景 1：Prompts 完全相同 - **行为**：只询问一次，使用新版本的 prompts - **原因**：避免重复输入相同的问题 #### 场景 2：Prompts 不同 - **行为**：分别询问原始版本和目标版本的 prompts - **原因**：需要分别计算原始和目标的模板渲染结果 #### 场景 3：新增模板 - **行为**：只询问新模板的 prompts - **原因**：原始版本不存在该模板 #### 场景 4：移除模板 - **行为**：只询问原始模板的 prompts - **原因**：需要计算原始版本用于三方合并 ### 文件处理策略升级过程会根据不同情况采取不同的处理策略： #### 1. **SKIP（跳过）** - 本地文件与目标文件相同 → 已是最新 - 合并后无变化 → 无需更新 - 模板未变且本地已删除 → 尊重本地删除 - 本地修改过的文件，模板已删除 → 保留本地修改 #### 2. **UPDATE（直接更新）** - 本地文件与原始模板相同 → 直接用新模板覆盖 ```bash ✓ Updated: src/main.ts ``` #### 3. **MERGE（合并）** - 本地有修改，模板也有更新 → 执行三方合并 - 无冲突时自动合并 ```bash ✓ Merged: vite.config.ts ``` #### 4. **MERGE with CONFLICTS（冲突合并）** - 合并时发现冲突 → 生成冲突标记 ```bash ⚠ Merged with conflicts: .eslintrc.js ``` #### 5. **ADD（新增）** - 新模板添加的文件 ```bash ✓ Added: src/types/global.d.ts ``` #### 6. **DELETE（删除）** - 模板删除了文件，且本地未修改 ```bash ✓ Deleted: old-config.js ``` ### 二进制文件处理升级过程能正确处理二进制文件（图片、字体等）： - **识别**：根据文件扩展名识别（.png, .jpg, .ttf, .woff 等） - **编码**：使用 base64 编码处理 - **比较**：通过内容哈希判断是否相同 - **合并**：冲突时默认使用新版本 ### Three-way Merge（三方合并）升级过程使用智能[三方合并算法](https://git-scm.com/docs/git-merge-file/zh_HANS-CN)，比较三个版本的文件，实际使用的是 git 命令 `git merge-file <Local> <Original> <Target>` 来执行三方合并。 ``` ┌─────────────┐ │ Original │ ← 之前安装的模板版本 │ (Base 版本) │ └──────┬──────┘ │ ┌───────┴───────┐ ↓ ↓ ┌──────────┐ ┌──────────┐ │ Local │ │ Target │ │ (当前版本) │ │ (新模板版本)│ └──────────┘ └──────────┘ │ │ └───────┬───────┘ ↓ ┌──────────┐ │ Merged │ ← 合并结果 └──────────┘ ``` ### 冲突解决当自动合并失败时，会在文件中生成冲突标记： ```javascript <<<<<<< HEAD // 当前项目的代码 const config = { port: 8080, old: 'value' }; ======= // 新模板的代码 const config = { port: 8100, new: 'value', updated: true }; >>>>>>> template ``` **解决冲突的步骤：** 1. **自动打开编辑器** - 如果安装了 VS Code，会自动打开冲突文件 2. **手动解决冲突** - 编辑文件，删除冲突标记，保留需要的代码 3. **测试验证** - 确保项目能正常运行 4. **提交更改** - `git add .` 和 `git commit` ## 贡献 ### 开发运行以下命令将会将本地的 dao 命令自动的 link 到全局，同时在退出时会自动取消 link ```bash pnpm dev # 运行开发环境，会监听文件变动并重新编译 ``` ### 模板调试将模板挂载全局 https://gitlab.daocloud.cn/ndx/frontend-engineering/vue-cli-plugins/dao-style-template#%E5%BC%80%E5%8F%91%E5%91%BD%E4%BB%A4 ```bash # create dao create test-project --local # list dao list --local # upgrade dao upgrade --local ```