# CLI 功能本地测试指南

本文档说明如何在本地测试 `@xagi/vite-plugin-design-mode` 的 CLI 安装和卸载功能。

## 前置准备

1. 确保项目已安装依赖：
```bash
npm install
```

2. 构建项目（编译 TypeScript 到 dist 目录）：
```bash
npm run build
```

这会编译所有源代码到 `dist/` 目录，包括 CLI 文件。

## 测试方法

### 方法 1: 使用 npm link（推荐）

这是最接近真实使用场景的测试方法。

#### 步骤 1: 在项目根目录创建链接

```bash
# 在项目根目录执行
npm link
```

这会在全局创建一个符号链接，指向当前项目。

#### 步骤 2: 在测试项目中链接插件

```bash
# 进入测试项目目录（例如 examples/demo）
cd examples/demo

# 链接插件
npm link @xagi/vite-plugin-design-mode
```

#### 步骤 3: 测试安装命令

```bash
# 在测试项目目录执行
npx @xagi/vite-plugin-design-mode install
```

#### 步骤 4: 测试卸载命令

```bash
# 在测试项目目录执行
npx @xagi/vite-plugin-design-mode uninstall
```

### 方法 2: 直接使用 node 运行编译后的文件

如果不想使用 npm link，可以直接运行编译后的 CLI 文件。

#### 步骤 1: 构建项目

```bash
npm run build
```

#### 步骤 2: 在测试项目中运行 CLI

```bash
# 进入测试项目目录
cd examples/demo

# 直接运行编译后的 CLI 文件
node ../../packages/plugin/dist/cli/index.js install
# 或
node ../../packages/plugin/dist/cli/index.js uninstall
```

### 方法 3: 使用 tsx 直接运行 TypeScript 文件（开发调试）

在开发过程中，可以使用 `tsx` 直接运行 TypeScript 文件，无需先编译。

#### 安装 tsx（如果还没有）

```bash
npm install -g tsx
# 或
npm install --save-dev tsx
```

#### 运行 CLI

```bash
# 在项目根目录
tsx packages/plugin/src/cli/index.ts install

# 或指定工作目录为测试项目
cd examples/demo
tsx ../../packages/plugin/src/cli/index.ts install
```

## 完整测试流程示例

以下是在 `examples/demo` 项目中完整测试安装和卸载的流程：

### 1. 准备测试环境

```bash
# 在项目根目录构建
npm run build

# 进入测试项目
cd examples/demo

# 备份当前的 vite.config.ts（可选）
cp vite.config.ts vite.config.ts.backup

# 备份 package.json（可选）
cp package.json package.json.backup
```

### 2. 测试安装功能

```bash
# 方法 A: 使用 npm link
npm link @xagi/vite-plugin-design-mode
npx @xagi/vite-plugin-design-mode install

# 方法 B: 直接运行编译后的文件
node ../../packages/plugin/dist/cli/index.js install

# 方法 C: 使用 tsx（开发时）
tsx ../../packages/plugin/src/cli/index.ts install
```

**验证安装结果：**

1. 检查 `package.json` 中是否添加了 `@xagi/vite-plugin-design-mode` 依赖
2. 检查 `vite.config.ts` 中是否添加了：
   - `import appdevDesignMode from '@xagi/vite-plugin-design-mode';`
   - `appdevDesignMode()` 在 plugins 数组中

### 3. 测试卸载功能

```bash
# 使用相同的方法运行卸载命令
npx @xagi/vite-plugin-design-mode uninstall
# 或
node ../../packages/plugin/dist/cli/index.js uninstall
# 或
tsx ../../packages/plugin/src/cli/index.ts uninstall
```

**验证卸载结果：**

1. 检查 `package.json` 中是否移除了 `@xagi/vite-plugin-design-mode` 依赖
2. 检查 `vite.config.ts` 中是否移除了：
   - import 语句
   - `appdevDesignMode()` 调用

### 4. 恢复测试环境（可选）

```bash
# 如果需要恢复到原始状态
cp vite.config.ts.backup vite.config.ts
cp package.json.backup package.json
```

## 测试不同场景

### 场景 1: 全新安装（插件未安装）

1. 确保测试项目的 `package.json` 中没有 `@xagi/vite-plugin-design-mode`
2. 确保 `vite.config.ts` 中没有相关配置
3. 运行 `install` 命令
4. 验证插件已安装且配置已添加

### 场景 2: 升级已安装的插件

1. 先在测试项目中安装旧版本（如果有）
2. 运行 `install` 命令
3. 验证插件已升级到最新版本

### 场景 3: 卸载已安装的插件

1. 确保插件已安装
2. 运行 `uninstall` 命令
3. 验证插件和配置都已移除

### 场景 4: 测试不同的包管理器

在不同使用不同包管理器的项目中测试：

```bash
# npm 项目
cd examples/basic
node ../../packages/plugin/dist/cli/index.js install

# pnpm 项目
cd examples/demo  # 如果有 pnpm-lock.yaml
node ../../packages/plugin/dist/cli/index.js install

# yarn 项目（如果有 yarn.lock）
node ../../packages/plugin/dist/cli/index.js install
```

## 调试技巧

### 查看详细输出

CLI 工具会输出详细的执行信息，包括：
- 检测到的包管理器
- 插件安装状态
- 执行的命令
- 配置文件修改情况

### 检查编译后的文件

确保 CLI 文件已正确编译：

```bash
# 检查 dist/cli 目录
ls -la dist/cli/

# 应该看到：
# - index.js
# - install.js
# - uninstall.js
```

### 常见问题排查

1. **命令未找到**
   - 确保已运行 `npm run build`
   - 检查 `packages/plugin/dist/cli/index.js` 是否存在
   - 如果使用 npm link，确保已正确链接

2. **权限问题**
   - 确保有写入 `package.json` 和 `vite.config.ts` 的权限

3. **配置文件格式问题**
   - CLI 会尝试处理不同的代码风格，但某些复杂格式可能需要手动调整

## 自动化测试脚本（可选）

可以创建一个测试脚本来自动化测试流程：

```bash
#!/bin/bash
# test-cli.sh

echo "构建项目..."
npm run build

echo "进入测试项目..."
cd examples/demo

echo "测试安装..."
node ../../packages/plugin/dist/cli/index.js install

echo "等待 2 秒..."
sleep 2

echo "测试卸载..."
node ../../packages/plugin/dist/cli/index.js uninstall

echo "测试完成！"
```

保存为 `test-cli.sh`，然后运行：

```bash
chmod +x test-cli.sh
./test-cli.sh
```