@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

$3

项目使用 @dao-style-template/ 组织下的 npm 包作为模板：

- @dao-style-template/base - 基础项目结构
- @dao-style-template/lint - ESLint 和代码格式化配置
- @dao-style-template/ci - CI/CD 配置

$3

模板的具体版本会自动写入项目的 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

$3

project-name 为项目名称，无需包含 ui ，ui 会根据项目名称自动生成。

`bash
dao create [options]
`

#### 基础用法

`bash
dao create my-app
`

创建新项目，自动：
- 下载最新版本的模板
- 生成项目文件
- 将模板版本写入 devDependencies
- 设置 postinstall 钩子

#### 可选参数

| 参数 | 简写 | 说明 | 默认值 |
| --------------------------- | ---- | ------------------------------------------------------------- | -------- |
| --initial-branch | -b | 设置初始分支名称 | master |
| --local | - | 使用本地模板（开发调试用） | - |
| --all-templates | - | 选择所有可用模板 | - |
| --answer | - | 提供模板提示的答案，格式：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
`

$3

`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.
`

$3

`bash
dao upgrade [options]
`

升级项目中的模板到最新版本，支持智能三方合并和冲突解决。

#### 可选参数

| 参数 | 说明 | 默认值 |
| --------- | -------------------------- | ------ |
| --local | 使用本地模板（开发调试用） | - |

#### 基础用法

`bash
dao upgrade
`

该命令会：
1. 检查 Git 状态 - 确保工作目录干净（可用 --force 跳过）
2. 检测可用更新 - 扫描所有已安装模板的新版本
3. 选择升级模板 - 交互式选择要升级的模板
4. 处理模板提示 - 智能判断是否需要重新回答 prompts
5. 执行三方合并 - 自动合并文件变更
6. 解决冲突 - 自动或手动解决冲突
7. 更新依赖 - 更新 package.json 并执行 pnpm install




$3

#### 升级前的建议

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...
`

🔄 升级机制详解

$3

升级时会智能判断是否需要重新回答 prompts：

#### 场景 1：Prompts 完全相同
- 行为：只询问一次，使用新版本的 prompts
- 原因：避免重复输入相同的问题

#### 场景 2：Prompts 不同
- 行为：分别询问原始版本和目标版本的 prompts
- 原因：需要分别计算原始和目标的模板渲染结果

#### 场景 3：新增模板
- 行为：只询问新模板的 prompts
- 原因：原始版本不存在该模板

#### 场景 4：移除模板
- 行为：只询问原始模板的 prompts
- 原因：需要计算原始版本用于三方合并

$3

升级过程会根据不同情况采取不同的处理策略：

#### 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
`

$3

升级过程能正确处理二进制文件（图片、字体等）：

- 识别：根据文件扩展名识别（.png, .jpg, .ttf, .woff 等）
- 编码：使用 base64 编码处理
- 比较：通过内容哈希判断是否相同
- 合并：冲突时默认使用新版本




$3

升级过程使用智能三方合并算法，比较三个版本的文件，实际使用的是 git 命令 git merge-file 来执行三方合并。


`
┌─────────────┐
│ Original │ ← 之前安装的模板版本
│ (Base 版本) │
└──────┬──────┘
│
┌───────┴───────┐
↓ ↓
┌──────────┐ ┌──────────┐
│ Local │ │ Target │
│ (当前版本) │ │ (新模板版本)│
└──────────┘ └──────────┘
│ │
└───────┬───────┘
↓
┌──────────┐
│ Merged │ ← 合并结果
└──────────┘
`


$3

当自动合并失败时，会在文件中生成冲突标记：

`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

贡献

$3

运行以下命令将会将本地的 dao 命令自动的 link 到全局，同时在退出时会自动取消 link
`bash
pnpm dev # 运行开发环境，会监听文件变动并重新编译
`

$3

将模板挂载全局 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
``