@quicksand-cloud/specs
Version:
QuickSand Cloud Specs CLI 工具 - 开发规范配置管理命令行工具，提供项目初始化、配置更新和验证功能
173 lines (119 loc) • 6.12 kB
Markdown
# @quicksand-cloud/specs
> QuickSand Cloud Specs CLI 工具 - 交互式开发规范配置生成器
[](https://badge.fury.io/js/@quicksand-cloud%2Fspecs)
[](https://opensource.org/licenses/MIT)
## 🚀 简介
QuickSand Cloud Specs CLI 是一个交互式的开发规范配置生成器，通过友好的交互界面让用户选择需要的配置插件，自动生成相应的配置文件和依赖。支持开发模式和生产模式，为项目快速配置企业级开发规范。
## 📦 安装
### 全局安装（推荐）
```bash
npm install -g @quicksand-cloud/specs
```
### 项目内安装
```bash
npm install --save-dev @quicksand-cloud/specs
```
## 🛠 使用方法
### 运行配置生成器
```bash
# 启动交互式配置生成器
specs
```
### 交互式流程
1. **选择模式**：首先选择是否启用开发模式
- **开发模式**：保持 `workspace:^` 依赖，适用于 monorepo 开发环境
- **生产模式**：将 `workspace:^` 依赖替换为 `latest`，适用于独立项目
2. **选择插件**：从以下选项中选择需要的配置插件
- 全部插件：一次性配置所有可用插件
- 单独选择：根据项目需求选择特定插件
3. **自动生成**：工具会自动生成配置文件并更新 `package.json`
### 使用示例
```bash
# 基本使用
$ specs
🚀 QuickSand Cloud Specs 配置生成器
? 是否启用开发模式？ › No
📦 生产模式已启用 - 将 workspace:^ 依赖替换为 latest
? 请选择要执行的插件配置： ›
✓ 全部插件
◯ EditorConfig 编辑器配置插件
◯ cSpell 拼写检查插件
◯ Git 版本控制插件
◯ Husky Git hooks 插件
◯ Lint-staged 预提交处理插件
◯ Prettier 代码格式化插件
◯ TypeScript 配置插件
◯ Oxlint 代码质量检查插件
◯ Commitlint Git 提交信息规范插件
```
## ⚙️ 配置详情
### 支持的配置插件
| 插件名 | 描述 | 相关包名 |
| -------------- | ---------------- | ----------------------------------- |
| `editorconfig` | 编辑器配置 | 无（生成 .editorconfig 文件） |
| `cSpell` | 拼写检查配置 | 无（生成 cSpell.json 文件） |
| `git` | Git 版本控制配置 | 无（生成 .gitignore 文件） |
| `husky` | Git hooks 配置 | husky |
| `lint-staged` | 预提交处理 | @quicksand-cloud/lint-staged-config |
| `prettier` | 代码格式化配置 | @quicksand-cloud/prettier-config |
| `typescript` | TypeScript 配置 | @quicksand-cloud/typescript-config |
| `oxlint` | 代码质量检查 | @quicksand-cloud/oxlint-config |
| `commitlint` | Git 提交信息规范 | @quicksand-cloud/commitlint-config |
### 配置文件生成
根据选择的插件，工具会自动生成以下配置文件：
#### 基础配置文件
- `.editorconfig` - 编辑器配置（editorconfig 插件）
- `cSpell.json` - 拼写检查配置（cSpell 插件）
- `.gitignore` - Git 忽略文件配置（git 插件）
#### Git Hooks 配置
- `.husky/pre-commit` - 预提交钩子（husky 插件）
- `.husky/commit-msg` - 提交信息钩子（husky 插件）
#### 代码质量配置
- `prettier.config.js` - Prettier 代码格式化配置（prettier 插件）
- `tsconfig.json` - TypeScript 配置（typescript 插件）
- `.oxlintrc.json` - Oxlint 代码检查配置（oxlint 插件）
- `commitlint.config.js` - Git 提交信息规范配置（commitlint 插件）
- `lint-staged.config.js` - 预提交处理配置（lint-staged 插件）
#### 项目配置更新
- `package.json` - 自动更新相关依赖和脚本
## 🎯 适用场景
- **任何 JavaScript/TypeScript 项目** - 前端、后端、全栈应用
- **Monorepo 项目** - 支持开发模式保持 workspace 依赖
- **团队协作项目** - 统一代码规范和提交规范
- **开源项目** - 快速配置标准化开发环境
## 🔧 开发模式 vs 生产模式
### 开发模式（Development Mode）
- 保持 `workspace:^` 依赖格式
- 适用于 monorepo 环境中的包开发
- 依赖指向本地工作区中的包
### 生产模式（Production Mode）
- 将 `workspace:^` 依赖替换为 `latest`
- 适用于独立项目或发布到 npm
- 依赖指向 npm 仓库中的最新版本
## 🔧 自动化集成
工具会自动配置以下集成：
### Git Hooks（通过 husky 插件）
- **pre-commit**: 自动运行 lint-staged 进行代码检查
- **commit-msg**: 自动验证提交信息格式
### 包管理器支持
- **Bun**: 优先支持，使用 `bunx` 命令
- **npm/yarn/pnpm**: 兼容支持
## 📋 依赖要求
- Node.js >= 18.0.0
- npm >= 8.0.0 或其他兼容的包管理器
## ⚠️ 注意事项
1. **配置覆盖**: 生成器会覆盖现有的同名配置文件，请提前备份重要配置
2. **依赖管理**: 工具会自动更新 `package.json`，建议在干净的 Git 状态下运行
3. **模式选择**:
- Monorepo 项目建议选择开发模式
- 独立项目建议选择生产模式
4. **权限问题**: 全局安装可能需要管理员权限
## 🔄 与其他配置包的关系
本工具是 QuickSand Cloud Specs 配置集合的交互式生成器，可以自动配置以下相关包：
- [@quicksand-cloud/commitlint-config](https://www.npmjs.com/package/@quicksand-cloud/commitlint-config) - Git 提交信息规范配置
- [@quicksand-cloud/prettier-config](https://www.npmjs.com/package/@quicksand-cloud/prettier-config) - 代码格式化配置
- [@quicksand-cloud/oxlint-config](https://www.npmjs.com/package/@quicksand-cloud/oxlint-config) - 代码质量检查配置
- [@quicksand-cloud/typescript-config](https://www.npmjs.com/package/@quicksand-cloud/typescript-config) - TypeScript 配置
- [@quicksand-cloud/lint-staged-config](https://www.npmjs.com/package/@quicksand-cloud/lint-staged-config) - 预提交处理配置
## 📄 许可证
MIT © QuickSand Cloud