@linyjs/cli 0.0.3 → 0.0.5

package/DESIGN.md

@@ -1,901 +0,0 @@
-# Ling CLI 命令行工具设计文档
-
-## 📖 目录
-
-- [1. 概述](#1-概述)
-- [2. 核心功能](#2-核心功能)
-- [3. 命令设计](#3-命令设计)
-- [4. 技术架构](#4-技术架构)
-- [5. 实现细节](#5-实现细节)
-- [6. 使用示例](#6-使用示例)
-- [7. 扩展计划](#7-扩展计划)
-
----
-
-## 1. 概述
-
-### 1.1 项目背景
-
-Ling 框架采用插件化架构，开发者需要频繁打包 `.mpk` 格式的插件文件。当前手动打包流程繁琐：
-
-```bash
-# 当前流程（繁琐）
-npm run build
-cd dist
-zip -r ../my-plugin.mpk .
-```
-
-**问题：**
-- ❌ 需要手动执行多个步骤
-- ❌ 容易遗漏 manifest.json 生成
-- ❌ 无法验证插件结构完整性
-- ❌ 不支持自动化 CI/CD 流程
-
-### 1.2 解决方案
-
-创建 `@linyjs/cli` 命令行工具，提供一键打包功能：
-
-```bash
-# 简化后的流程
-npx @linyjs/cli pack
-```
-
-**优势：**
-- ✅ 一键完成构建、验证、打包
-- ✅ 自动生成 manifest.json
-- ✅ 智能错误检测和提示
-- ✅ 支持 CI/CD 集成
-
-### 1.3 目标用户
-
-- **插件开发者** - 快速打包和测试插件
-- **CI/CD 流水线** - 自动化构建和发布
-- **插件市场管理员** - 批量处理插件包
-
----
-
-## 2. 核心功能
-
-### 2.1 插件打包 (`pack`)
-
-#### 主要功能
-
-1. **自动构建**
-   - 检测并执行 TypeScript 编译
-   - 支持自定义构建命令
-   - 增量构建优化
-
-2. **manifest.json 生成**
-   - 从 package.json 提取元数据
-   - 自动检测服务端/客户端入口
-   - 分析依赖关系
-
-3. **结构验证**
-   - 检查必需文件是否存在
-   - 验证 manifest.json 格式
-   - 检测常见配置错误
-
-4. **打包压缩**
-   - ZIP 格式压缩
-   - 优化文件大小
-   - 保留目录结构
-
-5. **签名支持** (可选)
-   - 为插件添加数字签名
-   - 验证签名完整性
-
-#### 工作流程
-
-```
-┌─────────────┐
-│ 读取配置     │
-│ package.json│
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ 构建项目     │
-│ npm run build│
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ 生成         │
-│ manifest.json│
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ 验证结构     │
-│ 检查必需文件  │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ 打包为 .mpk  │
-│ ZIP 压缩     │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ 输出结果     │
-│ 显示统计信息  │
-└─────────────┘
-```
-
-### 2.2 插件验证 (`validate`)
-
-#### 功能说明
-
-验证已存在的 `.mpk` 文件或插件目录是否符合规范。
-
-**检查项：**
-- ✅ manifest.json 存在且格式正确
-- ✅ 服务端/客户端入口文件存在
-- ✅ 依赖声明完整
-- ✅ 权限声明合理
-- ✅ 无安全风险（如路径遍历）
-
-#### 使用场景
-
-- 上传插件前的预检查
-- CI/CD 流水线质量门禁
-- 插件市场审核辅助
-
-### 2.3 插件发布 (`publish`)
-
-#### 功能说明
-
-将打包好的 `.mpk` 文件发布到插件市场。
-
-**功能点：**
-- 上传到中央仓库
-- 版本管理
-- 发布状态跟踪
-- 回滚支持
-
-#### 工作流程
-
-```bash
-# 1. 打包
-npx @linyjs/cli pack
-
-# 2. 发布
-npx @linyjs/cli publish my-plugin.mpk --token=xxx
-```
-
-### 2.4 项目初始化 (`init`)
-
-#### 功能说明
-
-快速创建新的插件项目模板。
-
-**提供的模板：**
-- `minimal` - 最小化插件（Hello World）
-- `full` - 完整功能插件（包含所有特性）
-- `admin-extension` - 管理后台扩展
-- `api-service` - 纯 API 服务插件
-
-#### 使用示例
-
-```bash
-# 创建新项目
-npx @linyjs/cli init my-plugin --template=full
-
-# 交互式选择
-npx @linyjs/cli init
-```
-
----
-
-## 3. 命令设计
-
-### 3.1 全局命令结构
-
-```bash
-@linyjs/cli <command> [options]
-```
-
-**Cleye 风格特点：**
-- 使用函数式 API 定义命令
-- 自动类型推断（无需手动定义接口）
-- 内置参数验证和错误提示
-
-### 3.2 详细命令定义
-
-#### `pack` - 打包插件
-
-```bash
-npx @linyjs/cli pack [options]
-```
-
-**选项：**
-
-| 选项 | 简写 | 类型 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--output` | `-o` | string | `.` | 输出目录 |
-| `--name` | `-n` | string | - | 插件名称（覆盖 package.json） |
-| `--version` | `-v` | string | - | 版本号（覆盖 package.json） |
-| `--no-build` | - | boolean | false | 跳过构建步骤 |
-| `--manifest` | - | string | - | 自定义 manifest.json 路径 |
-| `--sign` | - | boolean | false | 为插件添加签名 |
-| `--verbose` | - | boolean | false | 显示详细日志 |
-
-**示例：**
-
-```bash
-# 基本用法
-npx @linyjs/cli pack
-
-# 指定输出目录
-npx @linyjs/cli pack -o ./releases
-
-# 跳过构建（已有 dist/）
-npx @linyjs/cli pack --no-build
-
-# 详细模式
-npx @linyjs/cli pack --verbose
-```
-
-#### `validate` - 验证插件
-
-```bash
-npx @linyjs/cli validate <path> [options]
-```
-
-**参数：**
-- `path` - 插件路径（.mpk 文件或目录）
-
-**选项：**
-
-| 选项 | 简写 | 类型 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--strict` | - | boolean | false | 严格模式（警告也报错） |
-| `--json` | - | boolean | false | JSON 格式输出 |
-
-**示例：**
-
-```bash
-# 验证目录
-npx @linyjs/cli validate ./my-plugin
-
-# 验证 .mpk 文件
-npx @linyjs/cli validate my-plugin.mpk
-
-# JSON 输出
-npx @linyjs/cli validate my-plugin.mpk --json
-```
-
-#### `publish` - 发布插件
-
-```bash
-npx @linyjs/cli publish <file> [options]
-```
-
-**参数：**
-- `file` - .mpk 文件路径
-
-**选项：**
-
-| 选项 | 简写 | 类型 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--token` | `-t` | string | - | API Token（必需） |
-| `--registry` | - | string | - | 自定义仓库地址 |
-| `--dry-run` | - | boolean | false | 模拟运行（不实际上传） |
-
-**示例：**
-
-```bash
-# 发布到官方仓库
-npx @linyjs/cli publish my-plugin.mpk --token=xxx
-
-# 发布到私有仓库
-npx @linyjs/cli publish my-plugin.mpk \
-  --token=xxx \
-  --registry=https://my-registry.com
-```
-
-#### `init` - 初始化项目
-
-```bash
-npx @linyjs/cli init [name] [options]
-```
-
-**参数：**
-- `name` - 项目名称（可选）
-
-**选项：**
-
-| 选项 | 简写 | 类型 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--template` | `-t` | string | `minimal` | 项目模板 |
-| `--yes` | `-y` | boolean | false | 跳过确认 |
-
-**可用模板：**
-- `minimal` - 最小化插件
-- `full` - 完整功能插件
-- `admin-extension` - 管理后台扩展
-- `api-service` - 纯 API 服务
-
-**示例：**
-
-```bash
-# 交互式创建
-npx @linyjs/cli init
-
-# 指定名称和模板
-npx @linyjs/cli init my-blog --template=full
-
-# 非交互模式
-npx @linyjs/cli init my-plugin -t minimal -y
-```
-
----
-
-## 4. 技术架构
-
-### 4.1 项目结构
-
-```
-packages/cli/
-├── src/
-│   ├── index.ts              # CLI 入口
-│   ├── commands/             # 命令实现
-│   │   ├── pack.ts           # pack 命令
-│   │   ├── validate.ts       # validate 命令
-│   │   ├── publish.ts        # publish 命令
-│   │   └── init.ts           # init 命令
-│   ├── utils/                # 工具函数
-│   │   ├── builder.ts        # 构建工具
-│   │   ├── packager.ts       # 打包工具
-│   │   ├── validator.ts      # 验证工具
-│   │   ├── manifest.ts       # manifest 生成
-│   │   └── logger.ts         # 日志工具
-│   ├── templates/            # 项目模板
-│   │   ├── minimal/
-│   │   ├── full/
-│   │   ├── admin-extension/
-│   │   └── api-service/
-│   └── types/                # 类型定义
-│       ├── plugin.ts         # 插件相关类型
-│       └── config.ts         # 配置类型
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-### 4.2 技术栈
-
-**为什么选择 Cleye？**
-
-Cleye 相比 Commander.js 的优势：
-- ✅ **零配置 TypeScript** - 自动类型推断，无需手动定义类型
-- ✅ **更简洁的 API** - 函数式风格，代码更清晰
-- ✅ **内置帮助信息** - 自动生成美观的帮助文本
-- ✅ **更好的错误处理** - 自动验证参数类型
-- ✅ **更小体积** - 依赖更少，启动更快
-
-| 技术 | 用途 | 版本要求 |
-|------|------|----------|
-| **cleye** | CLI 框架（替代 commander） | ^1.3.0 |
-| **archiver** | ZIP 压缩 | ^6.0.0 |
-| **chalk** | 终端着色 | ^5.0.0 |
-| **inquirer** | 交互式问答 | ^9.0.0 |
-| **fs-extra** | 文件系统操作 | ^11.0.0 |
-| **zod** | 数据验证 | ^3.0.0 |
-| **ora** | 加载动画 | ^7.0.0 |
-
-### 4.3 核心模块设计
-
-#### 4.3.1 Builder（构建器）
-
-```typescript
-interface IBuilder {
-  // 检测是否需要构建
-  needsBuild(): boolean;
-  
-  // 执行构建
-  build(options: BuildOptions): Promise<void>;
-  
-  // 清理构建产物
-  clean(): Promise<void>;
-}
-
-class TypeScriptBuilder implements IBuilder {
-  constructor(private projectRoot: string);
-  
-  async build() {
-    // 1. 检查 tsconfig.json
-    // 2. 执行 tsc 或 esbuild
-    // 3. 返回构建结果
-  }
-}
-```
-
-#### 4.3.2 ManifestGenerator（清单生成器）
-
-```typescript
-interface IManifestGenerator {
-  // 从 package.json 生成 manifest
-  generateFromPackage(pkg: PackageJson): PluginManifest;
-  
-  // 合并自定义 manifest
-  mergeWithCustom(base: PluginManifest, customPath?: string): PluginManifest;
-  
-  // 验证 manifest 格式
-  validate(manifest: PluginManifest): ValidationResult;
-}
-
-class ManifestGenerator implements IManifestGenerator {
-  generateFromPackage(pkg: PackageJson): PluginManifest {
-    return {
-      name: pkg.name,
-      version: pkg.version,
-      description: pkg.description,
-      author: typeof pkg.author === 'string' 
-        ? pkg.author 
-        : pkg.author?.name,
-      serverEntry: this.detectServerEntry(),
-      clientEntry: this.detectClientEntry(),
-      dependencies: this.extractDependencies(pkg),
-      permissions: this.extractPermissions(pkg)
-    };
-  }
-}
-```
-
-#### 4.3.3 Packager（打包器）
-
-```typescript
-interface IPackager {
-  // 打包为 .mpk
-  pack(sourceDir: string, outputPath: string): Promise<PackResult>;
-  
-  // 获取打包统计信息
-  getStats(): PackStats;
-}
-
-class ZipPackager implements IPackager {
-  async pack(sourceDir: string, outputPath: string) {
-    // 1. 创建 ZIP 归档
-    // 2. 添加文件（排除 node_modules 等）
-    // 3. 计算文件大小和哈希
-    // 4. 返回打包结果
-  }
-}
-```
-
-#### 4.3.4 Validator（验证器）
-
-```typescript
-interface IValidator {
-  // 验证插件结构
-  validateStructure(pluginPath: string): ValidationResult;
-  
-  // 验证 manifest
-  validateManifest(manifest: PluginManifest): ValidationResult;
-  
-  // 安全检查
-  securityCheck(pluginPath: string): SecurityReport;
-}
-
-class PluginValidator implements IValidator {
-  validateStructure(pluginPath: string): ValidationResult {
-    const errors: ValidationError[] = [];
-    
-    // 检查必需文件
-    if (!existsSync(join(pluginPath, 'manifest.json'))) {
-      errors.push({
-        level: 'error',
-        message: 'manifest.json is missing'
-      });
-    }
-    
-    // 检查入口文件
-    // ...
-    
-    return { valid: errors.length === 0, errors };
-  }
-}
-```
-
-### 4.4 数据流图
-
-```
-┌─────────────────────────────────────────┐
-│          CLI Command Entry               │
-│   npx @linyjs/cli pack [options]        │
-└──────────────┬──────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────┐
-│         Configuration Loader            │
-│  - Read package.json                    │
-│  - Read .lingrc (if exists)             │
-│  - Merge CLI options                    │
-└──────────────┬──────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────┐
-│            Builder                      │
-│  - Detect build system                  │
-│  - Execute build                        │
-│  - Report errors                        │
-└──────────────┬──────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────┐
-│        Manifest Generator               │
-│  - Extract metadata                     │
-│  - Detect entries                       │
-│  - Generate manifest.json               │
-└──────────────┬──────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────┐
-│           Validator                     │
-│  - Validate structure                   │
-│  - Check dependencies                   │
-│  - Security scan                        │
-└──────────────┬──────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────┐
-│           Packager                      │
-│  - Create ZIP archive                   │
-│  - Compress files                       │
-│  - Calculate checksum                   │
-└──────────────┬──────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────┐
-│          Output Reporter                │
-│  - Display result                       │
-│  - Show statistics                      │
-│  - Provide next steps                   │
-└─────────────────────────────────────────┘
-```
-
----
-
-## 5. 实现细节
-
-### 5.1 配置文件支持
-
-#### `.lingrc.json`
-
-```json
-{
-  "build": {
-    "command": "npm run build",
-    "outputDir": "dist"
-  },
-  "pack": {
-    "exclude": [
-      "node_modules",
-      ".git",
-      "*.test.ts",
-      "*.spec.ts"
-    ],
-    "include": [
-      "**/*"
-    ]
-  },
-  "manifest": {
-    "customFields": {
-      "homepage": "https://example.com"
-    }
-  }
-}
-```
-
-### 5.2 错误处理策略
-
-```typescript
-class CliError extends Error {
-  constructor(
-    message: string,
-    public code: string,
-    public suggestions?: string[]
-  ) {
-    super(message);
-  }
-}
-
-// 使用示例
-try {
-  await builder.build();
-} catch (error) {
-  if (error.code === 'BUILD_FAILED') {
-    console.error('❌ Build failed');
-    console.log('\n💡 Suggestions:');
-    error.suggestions?.forEach(s => console.log(`   - ${s}`));
-    process.exit(1);
-  }
-}
-```
-
-### 5.3 日志系统
-
-```typescript
-import chalk from 'chalk';
-import ora from 'ora';
-
-class Logger {
-  info(message: string) {
-    console.log(chalk.blue('ℹ'), message);
-  }
-  
-  success(message: string) {
-    console.log(chalk.green('✓'), message);
-  }
-  
-  error(message: string) {
-    console.error(chalk.red('✗'), message);
-  }
-  
-  warn(message: string) {
-    console.warn(chalk.yellow('⚠'), message);
-  }
-  
-  spinner(text: string) {
-    return ora(text).start();
-  }
-}
-```
-
-### 5.4 进度指示
-
-```typescript
-const spinner = logger.spinner('Building project...');
-
-try {
-  await builder.build();
-  spinner.succeed('Build completed');
-} catch (error) {
-  spinner.fail('Build failed');
-  throw error;
-}
-```
-
-### 5.5 性能优化
-
-#### 增量构建
-
-```typescript
-class IncrementalBuilder {
-  private cacheDir = '.ling-cache';
-  
-  async build() {
-    const cacheHash = this.calculateHash();
-    const cachedHash = this.readCacheHash();
-    
-    if (cacheHash === cachedHash) {
-      logger.info('Using cached build');
-      return;
-    }
-    
-    await this.fullBuild();
-    this.writeCacheHash(cacheHash);
-  }
-}
-```
-
-#### 并行处理
-
-```typescript
-// 并行验证多个文件
-const validationResults = await Promise.all([
-  validateManifest(manifest),
-  validateEntries(entries),
-  validateDependencies(deps)
-]);
-```
-
----
-
-## 6. 使用示例
-
-### 6.1 基本工作流
-
-```bash
-# 1. 创建新项目
-npx @linyjs/cli init my-blog-plugin --template=full
-
-# 2. 进入项目目录
-cd my-blog-plugin
-
-# 3. 安装依赖
-npm install
-
-# 4. 开发插件
-# ... 编写代码 ...
-
-# 5. 打包插件
-npx @linyjs/cli pack
-
-# 6. 验证插件
-npx @linyjs/cli validate my-blog-plugin.mpk
-
-# 7. 发布插件
-npx @linyjs/cli publish my-blog-plugin.mpk --token=xxx
-```
-
-### 6.2 CI/CD 集成
-
-#### GitHub Actions
-
-```yaml
-name: Build and Publish Plugin
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install dependencies
-        run: npm ci
-      
-      - name: Build plugin
-        run: npx @linyjs/cli pack --output ./dist
-      
-      - name: Validate plugin
-        run: npx @linyjs/cli validate ./dist/*.mpk
-      
-      - name: Publish to registry
-        run: npx @linyjs/cli publish ./dist/*.mpk --token=${{ secrets.PLUGIN_TOKEN }}
-```
-
-### 6.3 本地开发
-
-```bash
-# 监听模式（自动重新打包）
-npx @linyjs/cli pack --watch
-
-# 快速迭代（跳过构建）
-npx @linyjs/cli pack --no-build
-
-# 输出到特定目录
-npx @linyjs/cli pack -o ~/ling-plugins/
-```
-
-### 6.4 批量处理
-
-```bash
-# 打包多个插件
-for dir in plugins/*/; do
-  cd "$dir"
-  npx @linyjs/cli pack -o ../../releases/
-  cd ../..
-done
-```
-
----
-
-## 7. 扩展计划
-
-### 7.1 短期计划（v0.1 - v0.3）
-
-#### v0.1 - MVP
-- ✅ `pack` 命令基础功能
-- ✅ 基本的 manifest 生成
-- ✅ ZIP 打包
-- ✅ 简单的错误提示
-
-#### v0.2 - 增强功能
-- 🔲 `validate` 命令
-- 🔲 完整的 manifest 验证
-- 🔲 详细的错误报告
-- 🔲 进度指示器
-
-#### v0.3 - 用户体验
-- 🔲 `init` 命令和项目模板
-- 🔲 交互式向导
-- 🔲 彩色输出
-- 🔲 配置文件支持
-
-### 7.2 中期计划（v0.4 - v0.6）
-
-#### v0.4 - 发布功能
-- 🔲 `publish` 命令
-- 🔲 插件市场 API 集成
-- 🔲 版本管理
-- 🔲 发布历史
-
-#### v0.5 - 高级功能
-- 🔲 插件签名
-- 🔲 增量构建
-- 🔲 缓存优化
-- 🔲 并行处理
-
-#### v0.6 - 生态系统
-- 🔲 插件依赖解析
-- 🔲 自动更新检查
-- 🔲 插件兼容性检查
-- 🔲 迁移工具
-
-### 7.3 长期愿景
-
-#### 插件市场集成
-- 在线浏览插件
-- 一键安装/卸载
-- 评分和评论
-- 使用统计
-
-#### 开发者工具
-- 插件调试工具
-- 性能分析
-- 依赖可视化
-- 代码生成器
-
-#### 企业级功能
-- 私有仓库支持
-- SSO 认证
-- 审计日志
-- 团队协作
-
----
-
-## 8. 附录
-
-### A. 参考资源
-
-- [Cleye](https://github.com/zthh/cleye) - 现代化 CLI 框架
-- [Archiver](https://github.com/archiverjs/node-archiver) - ZIP 压缩
-- [Inquirer](https://github.com/SBoudrias/Inquirer.js) - 交互式问答
-- [Chalk](https://github.com/chalk/chalk) - 终端着色
-
-### B. 类似工具
-
-- **create-react-app** - React 项目脚手架
-- **vue-cli** - Vue.js CLI 工具
-- **angular-cli** - Angular CLI
-- **webpack-cli** - Webpack 命令行
-
-### C. 最佳实践
-
-1. **用户友好**
-   - 清晰的错误消息
-   - 提供解决建议
-   - 友好的交互体验
-
-2. **性能优先**
-   - 增量构建
-   - 缓存利用
-   - 并行处理
-
-3. **可扩展性**
-   - 插件化架构
-   - 自定义配置
-   - 钩子系统
-
-4. **安全性**
-   - 输入验证
-   - 沙箱执行
-   - 签名验证
-
----
-
-## 总结
-
-本设计文档详细描述了 `@linyjs/cli` 命令行工具的架构和功能。通过提供一键打包、验证、发布等功能，将极大提升 Ling 框架插件开发的效率和体验。
-
-**核心价值：**
-- 🚀 **提升效率** - 从多步手动操作简化为一键命令
-- ✅ **保证质量** - 自动验证和错误检测
-- 🔄 **支持自动化** - CI/CD 友好
-- 📦 **标准化** - 统一的打包流程和格式
-
-下一步将开始实现 v0.1 MVP 版本，首先完成 `pack` 命令的基础功能。