npm - @linyjs/cli - Versions diffs - 0.0.4 → 0.0.5 - Mend

@linyjs/cli 0.0.4 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/DESIGN.md DELETED Viewed

@@ -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` 命令的基础功能。