@linyjs/cli 0.0.2

package/README.md

@@ -0,0 +1,596 @@
+# @linyjs/cli - Ling 框架命令行工具
+
+## 📦 简介
+
+`@linyjs/cli` 是 Ling 框架的官方命令行工具，提供**零配置**的插件打包功能。
+
+**核心理念：**
+- ✅ **零配置** - 无需配置 webpack、rollup 等构建工具
+- ✅ **智能构建** - CLI 自动处理所有构建细节
+- ✅ **开箱即用** - 只需编写 TypeScript/TSX 代码即可打包
+- ✅ **优化默认值** - 内置 esbuild，自动 bundle、minify、tree shaking
+
+---
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 全局安装（推荐）
+npm install -g @linyjs/cli
+
+# 或在项目中使用
+npx @linyjs/cli <command>
+```
+
+### 基本用法
+
+```bash
+# 查看帮助
+npx @linyjs/cli
+
+# 创建新插件项目
+npx @linyjs/cli init my-plugin
+
+# 打包插件
+cd my-plugin
+npx @linyjs/cli pack
+
+# 开发模式（打包 + 安装 + 注册）
+npx @linyjs/cli dev
+
+# 验证插件
+npx @linyjs/cli validate my-plugin.mpk
+```
+
+---
+
+## 📖 命令参考
+
+### `pack` - 打包插件
+
+将插件项目打包为 `.mpk` 文件。
+
+#### 用法
+
+```bash
+npx @linyjs/cli pack [options]
+```
+
+#### 选项
+
+| 选项 | 简写 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--output` | `-o` | string | `.` | 输出目录 |
+| `--name` | `-n` | string | - | 插件名称（覆盖 package.json） |
+| `--version` | `-v` | string | - | 版本号（覆盖 package.json） |
+| `--build` | - | boolean | true | 执行构建步骤（使用 `--no-build` 跳过） |
+| `--manifest` | - | string | - | 自定义 manifest.json 路径 |
+| `--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
+
+# 自定义版本
+npx @linyjs/cli pack -v 1.0.0
+```
+
+#### 工作流程
+
+```
+1. 读取 package.json
+2. 执行构建（npm run build）
+3. 生成 manifest.json
+4. 验证插件结构
+5. 打包为 .mpk 文件
+6. 显示结果统计
+```
+
+---
+
+### `dev` - 开发模式 ⭐
+
+快速开发工作流：打包插件 → 安装到 extensions → 注册到 packages.json
+
+#### 用法
+
+```bash
+npx @linyjs/cli dev [options]
+```
+
+#### 选项
+
+| 选项 | 简写 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--target` | `-t` | string | 自动检测 | extensions 目录路径 |
+| `--verbose` | - | boolean | false | 显示详细日志 |
+
+#### 工作流程
+
+```
+1. 打包插件（生成 .mpk）
+2. 解压到 extensions/<plugin-name>/
+3. 读取 manifest.json
+4. 更新 packages.json
+5. 清理临时文件
+```
+
+#### 示例
+
+```bash
+# 基本用法（自动检测 extensions 目录）
+npx @linyjs/cli dev
+
+# 指定目标目录
+npx @linyjs/cli dev --target /path/to/ling/packages/ssr/extensions
+
+# 详细模式
+npx @linyjs/cli dev --verbose
+```
+
+#### 输出示例
+
+```
+🚀 Ling Plugin Dev Mode
+
+✔ Packing plugin...
+✔ Plugin packed: my-plugin-1.0.0.mpk
+✔ Installing to extensions...
+✔ Installed to: /path/to/extensions/my-plugin
+✔ Registering plugin...
+✔ Plugin registered in packages.json
+
+✓ Development setup complete!
+
+Plugin installed:
+  Name: my-plugin
+  Path: /path/to/extensions/my-plugin
+  Status: enabled
+
+Next steps:
+  1. Restart SSR server:
+     cd packages/ssr && npx tsx src/demo/dev-server-with-pkg.tsx
+  2. Or use hot reload (if supported)
+  3. Test your plugin in the browser
+```
+
+#### 优势
+
+✅ **一键部署** - 无需手动复制文件  
+✅ **自动注册** - 自动更新 packages.json  
+✅ **智能检测** - 自动查找 extensions 目录  
+✅ **增量更新** - 覆盖旧版本，保留配置  
+✅ **清理临时文件** - 不留下垃圾文件  
+
+---
+
+### `init` - 创建项目 ⭐
+
+从 npm 下载模板，快速创建新的插件项目。
+
+#### 用法
+
+```bash
+npx @linyjs/cli init [name]
+```
+
+#### 参数
+
+- `name` - 项目名称（默认：`my-plugin`）
+
+#### 示例
+
+```bash
+# 创建名为 my-blog 的插件项目
+npx @linyjs/cli init my-blog
+
+# 使用默认名称
+npx @linyjs/cli init
+```
+
+#### 工作流程
+
+```
+1. 从 npm 下载 @linyjs/plugin-templates
+2. 创建项目目录
+3. 复制模板文件
+4. 显示下一步操作指南
+```
+
+#### 输出示例
+
+```
+🚀 Ling Plugin Project Creator
+
+✔ Downloading template from npm...
+✔ Template downloaded
+
+✓ Project created successfully!
+
+Next steps:
+  1. Navigate to your project:
+     cd my-plugin
+  2. Install dependencies:
+     npm install
+  3. Start development:
+     npm run dev
+  4. Pack for deployment:
+     npx @linyjs/cli pack
+
+Learn more:
+  - Plugin Development Guide: ...
+  - CLI Documentation: ...
+```
+
+#### 模板内容
+
+创建的插件项目包含：
+
+```
+my-plugin/
+├── package.json          # 预配置的依赖和脚本
+├── tsconfig.json         # TypeScript 配置
+├── README.md             # 项目说明
+├── .gitignore            # Git 忽略文件
+└── src/
+    ├── server/
+    │   └── index.ts      # 服务端模块示例
+    └── client/
+        └── index.tsx     # 客户端模块示例
+```
+
+**特性：**
+- ✅ TypeScript 支持
+- ✅ React 19 支持
+- ✅ 零配置构建（使用 `@linyjs/cli`）
+- ✅ 示例代码和注释
+- ✅ 开箱即用
+
+---
+
+### `validate` - 验证插件
+
+验证 `.mpk` 文件或插件目录是否符合规范。
+
+#### 用法
+
+```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
+```
+
+---
+
+### `init` - 初始化项目
+
+快速创建新的插件项目模板。
+
+#### 用法
+
+```bash
+npx @linyjs/cli init [name] [options]
+```
+
+#### 参数
+
+- `name` - 项目名称（可选）
+
+#### 选项
+
+| 选项 | 简写 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--template` | `-t` | string | `minimal` | 项目模板 |
+| `--yes` | `-y` | boolean | false | 跳过确认 |
+
+#### 可用模板
+
+- `minimal` - 最小化插件（Hello World）
+- `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
+```
+
+---
+
+## 💡 使用场景
+
+### 1. 本地开发
+
+#### 方式 A：使用 dev 命令（推荐）⭐
+
+```bash
+# 在插件项目中
+cd my-plugin
+
+# 一键打包、安装、注册
+npx @linyjs/cli dev
+
+# 重启 SSR 服务器即可看到效果
+cd ../ssr && npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+**优势：**
+- ✅ 自动打包
+- ✅ 自动复制到 extensions
+- ✅ 自动注册到 packages.json
+- ✅ 清理临时文件
+
+#### 方式 B：手动流程
+
+```bash
+# 在插件项目中
+cd my-plugin
+
+# 打包并测试
+npx @linyjs/cli pack
+
+# 复制到 extensions 目录
+cp my-plugin-1.0.0.mpk ../ssr/extensions/
+
+# 重启 SSR 服务器
+cd ../ssr && npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+### 2. CI/CD 集成
+
+```yaml
+# .github/workflows/build.yml
+name: Build 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: Pack plugin
+        run: npx @linyjs/cli pack --output ./dist
+      
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: plugin
+          path: ./dist/*.mpk
+```
+
+### 3. 批量处理
+
+```bash
+# 打包多个插件
+for dir in plugins/*/; do
+  cd "$dir"
+  npx @linyjs/cli pack -o ../../releases/
+  cd ../..
+done
+```
+
+---
+
+## 🔧 配置
+
+### `.lingrc.json`
+
+可以在项目根目录创建 `.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"
+    }
+  }
+}
+```
+
+---
+
+## 🎨 输出示例
+
+### 成功打包
+
+```
+📦 Ling Plugin Packer
+
+✔ Package.json loaded
+✔ Build completed
+✔ Manifest generated
+✔ Structure validated
+✔ Plugin packed successfully
+
+✓ Plugin ready!
+  File: /path/to/my-plugin-1.0.0.mpk
+  Size: 245.67 KB
+  Version: 1.0.0
+
+Next steps:
+  1. Test the plugin:
+     cp /path/to/my-plugin-1.0.0.mpk /path/to/ling/packages/ssr/extensions/
+  2. Restart SSR server:
+     cd packages/ssr && npx tsx src/demo/dev-server-with-pkg.tsx
+  3. Validate the plugin:
+     npx @linyjs/cli validate /path/to/my-plugin-1.0.0.mpk
+```
+
+### 验证失败
+
+```
+📦 Ling Plugin Packer
+
+✔ Package.json loaded
+✔ Build completed
+✔ Manifest generated
+✗ Validation failed
+
+Validation errors:
+  - Server entry not found: server/index.js
+  - Client entry not found: client/index.js
+```
+
+---
+
+## 🛠️ 技术栈
+
+- **[Cleye](https://github.com/zthh/cleye)** - 现代化 CLI 框架
+- **[Archiver](https://github.com/archiverjs/node-archiver)** - ZIP 压缩
+- **[Chalk](https://github.com/chalk/chalk)** - 终端着色
+- **[Ora](https://github.com/sindresorhus/ora)** - 加载动画
+- **[FS Extra](https://github.com/jprichardson/node-fs-extra)** - 文件系统操作
+
+---
+
+## 📝 开发指南
+
+### 本地开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/linyjs/ling.git
+cd ling/packages/cli
+
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+
+# 测试
+node dist/index.js pack --help
+```
+
+### 添加新命令
+
+1. 在 `src/commands/` 目录下创建新文件
+2. 实现命令逻辑
+3. 在 `src/index.ts` 中注册命令
+
+---
+
+## ❓ 常见问题
+
+### Q: 如何使用 dev 命令快速开发？
+
+```bash
+# 在插件项目目录中
+cd my-plugin
+
+# 一键打包、安装、注册
+npx @linyjs/cli dev
+
+# 如果自动检测失败，指定目标目录
+npx @linyjs/cli dev --target /path/to/ling/packages/ssr/extensions
+```
+
+详见：[`dev` - 开发模式](#dev---开发模式-)
+
+### Q: 如何跳过构建步骤？
+
+```bash
+npx @linyjs/cli pack --no-build
+```
+
+### Q: 如何指定输出目录？
+
+```bash
+npx @linyjs/cli pack -o ./releases
+```
+
+### Q: 打包后文件在哪里？
+
+默认在当前目录，文件名格式为 `{name}-{version}.mpk`。
+
+### Q: 如何验证插件？
+
+```bash
+npx @linyjs/cli validate my-plugin.mpk
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🔗 相关链接
+
+- [Ling 框架文档](https://github.com/linyjs/ling)
+- [插件开发指南](../../spec/插件开发指南.md)
+- [问题反馈](https://github.com/linyjs/ling/issues)