@linyjs/cli 0.0.4 → 0.0.5

package/ZERO_CONFIG_GUIDE.md

@@ -1,462 +0,0 @@
-# 零配置插件开发指南
-
-## 🎯 核心理念
-
-**你只需要：**
-1. 编写 TypeScript/TSX 代码
-2. 运行 `npx @linyjs/cli pack`
-3. 得到优化后的 `.mpk` 文件
-
-**不需要：**
-- ❌ 配置 webpack
-- ❌ 配置 rollup
-- ❌ 配置 babel
-- ❌ 配置 esbuild
-- ❌ 处理 bundle 优化
-- ❌ 管理外部依赖
-
-CLI 会自动处理所有构建细节！
-
----
-
-## 🚀 5分钟快速开始
-
-### 步骤 1: 创建项目结构
-
-```bash
-mkdir my-plugin && cd my-plugin
-npm init -y
-```
-
-### 步骤 2: 安装依赖
-
-```bash
-npm install @linyjs/server-module-interface @linyjs/client-module-interface react
-npm install -D typescript @types/react
-```
-
-### 步骤 3: 创建 tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "lib": ["ES2020", "DOM"],
-    "jsx": "react-jsx",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "moduleResolution": "node"
-  },
-  "include": ["src/**/*"]
-}
-```
-
-**注意：** 不需要配置 `outDir`，CLI 会处理输出！
-
-### 步骤 4: 编写代码
-
-**src/server/index.ts**
-```typescript
-import type { IModule } from '@linyjs/server-module-interface';
-
-class HelloController {
-  getRoutes() {
-    return [{
-      method: 'GET' as const,
-      path: '/api/hello',
-      middlewares: [],
-      responseType: 'json' as const,
-      handler: async () => {
-        return { message: 'Hello from plugin!' };
-      }
-    }];
-  }
-}
-
-export const helloServerModule: IModule = {
-  name: 'helloServer',
-  serviceDefs: [{
-    serviceTag: 'helloController',
-    serviceImpl: HelloController,
-    meta: { usageType: 'controller' }
-  }]
-};
-```
-
-**src/client/index.tsx**
-```typescript
-import type { IModule } from '@linyjs/client-module-interface';
-import React from 'react';
-
-function HelloPage() {
-  return <div>Hello from plugin!</div>;
-}
-
-export const helloClientModule: IModule = {
-  name: 'helloClient',
-  serviceDefs: [{
-    serviceTag: 'helloRoute',
-    serviceImpl: class {
-      basePath = '/hello';
-      getRoutes() {
-        return [{
-          path: '/',
-          component: HelloPage,
-          key: 'hello-page',
-          meta: { title: 'Hello' }
-        }];
-      }
-    },
-    meta: { usageType: 'route' }
-  }]
-};
-```
-
-### 步骤 5: 一键打包
-
-```bash
-npx @linyjs/cli pack
-```
-
-**就这么简单！** 🎉
-
-CLI 会自动：
-1. ✅ 检测入口文件（`src/server/index.ts` 和 `src/client/index.tsx`）
-2. ✅ 使用 esbuild 进行优化构建
-3. ✅ Bundle 所有依赖
-4. ✅ Minify 代码（减小体积）
-5. ✅ Tree shaking（移除未使用代码）
-6. ✅ 处理外部依赖（react、express 等）
-7. ✅ 生成 manifest.json
-8. ✅ 验证插件结构
-9. ✅ 打包为 `.mpk` 文件
-
-### 步骤 6: 查看结果
-
-```
-✓ Plugin ready!
-  File: /path/to/my-plugin-1.0.0.mpk
-  Size: 45.23 KB
-  Version: 1.0.0
-```
-
----
-
-## 📂 标准项目结构
-
-CLI 期望以下目录结构（约定优于配置）：
-
-```
-my-plugin/
-├── package.json
-├── tsconfig.json          # 只需要基本的 TS 配置
-├── src/
-│   ├── server/
-│   │   └── index.ts       # 服务端入口（必需）
-│   ├── client/
-│   │   └── index.tsx      # 客户端入口（可选）
-│   └── shared/
-│       └── types.ts       # 共享类型（可选）
-└── README.md
-```
-
-**入口文件命名约定：**
-
-| 类型 | 路径 | 说明 |
-|------|------|------|
-| 服务端 | `src/server/index.ts` | 主入口文件 |
-| 客户端 | `src/client/index.tsx` | 主入口文件 |
-
-如果找不到这些文件，CLI 会尝试其他常见模式：
-- `src/server.ts`
-- `src/client.tsx`
-- `server/index.ts`
-- `client/index.tsx`
-
----
-
-## ⚙️ 默认行为详解
-
-### 1. 自动使用 esbuild
-
-无论你项目中是否有 webpack、rollup 或 tsc 配置，CLI **始终使用 esbuild** 进行构建。
-
-**为什么？**
-- ⚡ **速度** - 比 webpack 快 10-100 倍
-- 📦 **体积小** - 更好的 tree shaking
-- 🔧 **零配置** - 无需复杂的配置文件
-- 🎯 **优化** - 内置 minify、bundle、code splitting
-
-### 2. 智能外部依赖处理
-
-CLI 自动将以下依赖标记为 external（不打包）：
-
-```typescript
-const defaultExternal = [
-  'react',           // 由 SSR 宿主提供
-  'react-dom',       // 由 SSR 宿主提供
-  'express',         // 由 Node.js 环境提供
-  '@linyjs/*',       // Ling 框架核心
-  '@ling/*'          // 兼容旧版本
-];
-```
-
-**好处：**
-- 📉 **减小体积** - 避免重复打包共享库
-- ⚡ **加载更快** - 利用浏览器/Node.js 缓存
-- 🔄 **版本一致** - 确保使用宿主环境的版本
-
-### 3. 自动优化
-
-默认启用的优化：
-
-```bash
-# Server Bundle
---bundle              # 打包所有依赖
---minify              # 代码压缩
---sourcemap           # 生成 sourcemap
---platform=node       # Node.js 优化
---target=node18       # 目标平台
-
-# Client Bundle
---bundle              # 打包所有依赖
---minify              # 代码压缩
---sourcemap           # 生成 sourcemap
---platform=browser    # 浏览器优化
---target=es2020       # 目标平台
-```
-
-### 4. 输出结构
-
-CLI 生成的标准输出：
-
-```
-dist/
-├── server/
-│   └── index.js       # 服务端 bundle
-├── client/
-│   └── index.js       # 客户端 bundle
-└── manifest.json      # 插件清单
-```
-
----
-
-## 🎨 自定义（可选）
-
-虽然零配置是默认行为，但你仍然可以自定义：
-
-### 方式 1: CLI 选项
-
-```bash
-# 跳过构建（使用已有 dist/）
-npx @linyjs/cli pack --no-build
-
-# 详细模式（查看构建详情）
-npx @linyjs/cli pack --verbose
-
-# 指定输出目录
-npx @linyjs/cli pack -o ./releases
-```
-
-### 方式 2: .lingrc.json（高级）
-
-```json
-{
-  "build": {
-    "external": [
-      "react",
-      "lodash",        // 添加额外的 external 依赖
-      "moment"
-    ],
-    "exclude": [
-      "*.test.ts",     // 排除测试文件
-      "**/__tests__/**"
-    ]
-  }
-}
-```
-
-### 方式 3: package.json 元数据
-
-```json
-{
-  "name": "@my-org/my-plugin",
-  "version": "1.0.0",
-  "description": "My awesome plugin",
-  "author": "Your Name",
-  "ling": {
-    "permissions": [
-      "article:read",
-      "article:write"
-    ]
-  }
-}
-```
-
----
-
-## 💡 最佳实践
-
-### 1. 保持简单
-
-```typescript
-// ✅ 推荐：简单的入口文件
-export const myServerModule: IModule = {
-  name: 'myServer',
-  serviceDefs: [...]
-};
-
-// ❌ 避免：复杂的构建逻辑
-// 不需要 webpack.config.js
-// 不需要 rollup.config.js
-// 不需要 babel.config.js
-```
-
-### 2. 使用 TypeScript
-
-```json
-// tsconfig.json - 保持简洁
-{
-  "compilerOptions": {
-    "strict": true,
-    "esModuleInterop": true
-  }
-}
-```
-
-### 3. 合理的依赖管理
-
-```json
-{
-  "dependencies": {
-    "@linyjs/server-module-interface": "^0.0.1",
-    "@linyjs/client-module-interface": "^0.0.1",
-    "react": "^19.0.0"
-    // ❌ 不要添加 express、webpack 等构建工具
-  }
-}
-```
-
-### 4. 清晰的目录结构
-
-```
-src/
-├── server/          # 服务端代码
-│   ├── index.ts     # 入口
-│   ├── controllers/ # 控制器
-│   └── services/    # 服务
-├── client/          # 客户端代码
-│   ├── index.tsx    # 入口
-│   ├── components/  # 组件
-│   └── pages/       # 页面
-└── shared/          # 共享代码
-    └── types.ts     # 类型定义
-```
-
----
-
-## 🐛 常见问题
-
-### Q1: 我需要配置 webpack 吗？
-
-**不需要！** CLI 内置了 esbuild，自动处理所有构建细节。
-
-```bash
-# 只需运行
-npx @linyjs/cli pack
-```
-
-### Q2: 如何添加第三方库？
-
-直接安装即可，CLI 会自动处理：
-
-```bash
-npm install lodash
-```
-
-在代码中使用：
-
-```typescript
-import _ from 'lodash';
-
-// CLI 会自动判断是否打包或 external
-```
-
-如果需要 external（减小体积），在 `.lingrc.json` 中配置：
-
-```json
-{
-  "build": {
-    "external": ["lodash"]
-  }
-}
-```
-
-### Q3: 如何调试构建问题？
-
-使用 `--verbose` 模式：
-
-```bash
-npx @linyjs/cli pack --verbose
-```
-
-会显示：
-- 检测到的构建系统
-- 使用的构建命令
-- 每个 bundle 的大小
-- 详细的错误信息
-
-### Q4: 支持 JSX/TSX 吗？
-
-**完全支持！** CLI 自动处理 JSX 转换。
-
-```tsx
-// src/client/index.tsx
-function MyComponent() {
-  return <div>Hello</div>;  // ✅ 正常工作
-}
-```
-
-### Q5: 如何处理环境变量？
-
-在代码中直接使用：
-
-```typescript
-const apiKey = process.env.MY_API_KEY;
-```
-
-CLI 不会处理环境变量，它们会在运行时从宿主环境读取。
-
----
-
-## 📊 性能对比
-
-| 构建方式 | 配置复杂度 | 构建速度 | 输出体积 | 推荐度 |
-|---------|-----------|---------|---------|--------|
-| **CLI (esbuild)** | ⭐ 零配置 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅✅✅ |
-| Webpack | ⭐⭐⭐⭐ 复杂 | ⭐⭐ | ⭐⭐⭐ | ❌ |
-| Rollup | ⭐⭐⭐ 中等 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ❌ |
-| tsc only | ⭐⭐ 简单 | ⭐⭐⭐⭐ | ⭐⭐ | ❌ |
-
----
-
-## 🎓 总结
-
-**零配置插件开发的三个原则：**
-
-1. **约定优于配置** - 遵循标准目录结构
-2. **智能默认值** - CLI 自动选择最优策略
-3. **渐进式增强** - 需要时可以自定义
-
-**你只需要：**
-```bash
-# 1. 写代码
-# 2. 打包
-npx @linyjs/cli pack
-
-# 完成！✨
-```
-
-享受简单、高效的插件开发体验吧！🚀

package/src/commands/dev.ts

@@ -1,251 +0,0 @@
-/**
- * Dev command - Quick plugin development workflow
- * 
- * Packs the plugin, copies to extensions folder, and registers in packages.json
- */
-
-import fs from 'fs';
-import path from 'path';
-import chalk from 'chalk';
-import ora from 'ora';
-import { packPlugin } from './pack.js';
-
-interface DevOptions {
-  target?: string;
-  verbose: boolean;
-}
-
-/**
- * Load .env file and return environment variables
- */
-function loadEnvConfig(projectRoot: string): Record<string, string> {
-  const envPath = path.join(projectRoot, '.env');
-  
-  if (!fs.existsSync(envPath)) {
-    // Try parent directories (monorepo structure)
-    const parentEnvPath = path.join(projectRoot, '..', '.env');
-    if (fs.existsSync(parentEnvPath)) {
-      return parseEnvFile(parentEnvPath);
-    }
-    return {};
-  }
-  
-  return parseEnvFile(envPath);
-}
-
-/**
- * Parse .env file content
- */
-function parseEnvFile(envPath: string): Record<string, string> {
-  const content = fs.readFileSync(envPath, 'utf-8');
-  const config: Record<string, string> = {};
-  
-  content.split('\n').forEach(line => {
-    line = line.trim();
-    if (line && !line.startsWith('#')) {
-      const [key, ...valueParts] = line.split('=');
-      if (key && valueParts.length > 0) {
-        config[key.trim()] = valueParts.join('=').trim();
-      }
-    }
-  });
-  
-  return config;
-}
-
-/**
- * Execute dev workflow: pack -> copy -> register
- */
-export async function devPlugin(options: DevOptions) {
-  const projectRoot = process.cwd();
-  
-  console.log(chalk.blue('🚀 Ling Plugin Dev Mode\n'));
-  
-  // Load environment configuration
-  const envConfig = loadEnvConfig(projectRoot);
-  
-  // Step 1: Pack the plugin
-  const spinner1 = ora('Packing plugin...').start();
-  
-  try {
-    // Create temporary output directory
-    const tempOutputDir = path.join(projectRoot, '.ling-tmp');
-    
-    await packPlugin({
-      output: tempOutputDir,
-      build: true,
-      verbose: options.verbose
-    });
-    
-    // Find the generated .mpk file
-    const mpkFiles = fs.readdirSync(tempOutputDir).filter(f => f.endsWith('.mpk'));
-    
-    if (mpkFiles.length === 0) {
-      spinner1.fail('No .mpk file generated');
-      process.exit(1);
-    }
-    
-    const mpkFile = mpkFiles[0];
-    const mpkPath = path.join(tempOutputDir, mpkFile);
-    
-    spinner1.succeed(`Plugin packed: ${mpkFile}`);
-    
-    // Step 2: Determine target extensions directory
-    const targetDir = options.target || findExtensionsDir(projectRoot, envConfig);
-    
-    if (!targetDir) {
-      spinner1.fail('Cannot find extensions directory');
-      console.error(chalk.red('\nPlease specify target directory:'));
-      console.error(chalk.gray('\nOption 1: Use --target flag'));
-      console.error(chalk.gray('  npx @linyjs/cli dev --target /path/to/extensions'));
-      console.error(chalk.gray('\nOption 2: Add to .env file'));
-      console.error(chalk.gray('  EXTENSIONS_DIR=/path/to/ling/packages/ssr/extensions'));
-      process.exit(1);
-    }
-    
-    // Step 3: Extract and copy to extensions
-    const spinner2 = ora('Installing to extensions...').start();
-    
-    const pluginName = mpkFile.replace('.mpk', '').replace(/-\d+\.\d+\.\d+$/, '');
-    const installPath = path.join(targetDir, pluginName);
-    
-    // Remove old installation if exists
-    if (fs.existsSync(installPath)) {
-      fs.rmSync(installPath, { recursive: true, force: true });
-    }
-    
-    // Create installation directory
-    fs.mkdirSync(installPath, { recursive: true });
-    
-    // Extract .mpk file (it's a ZIP)
-    await extractMpk(mpkPath, installPath);
-    
-    spinner2.succeed(`Installed to: ${installPath}`);
-    
-    // Step 4: Register in packages.json
-    const spinner3 = ora('Registering plugin...').start();
-    
-    const packagesJsonPath = path.join(targetDir, 'packages.json');
-    
-    let packages: any[] = [];
-    
-    if (fs.existsSync(packagesJsonPath)) {
-      const content = fs.readFileSync(packagesJsonPath, 'utf-8');
-      packages = JSON.parse(content);
-    }
-    
-    // Read manifest from installed plugin
-    const manifestPath = path.join(installPath, 'manifest.json');
-    let manifest: any = {};
-    
-    if (fs.existsSync(manifestPath)) {
-      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-    }
-    
-    // Check if already registered
-    const existingIndex = packages.findIndex(p => p.name === pluginName);
-    
-    const packageInfo = {
-      name: pluginName,
-      version: manifest.version || '1.0.0',
-      installPath: `extensions/${pluginName}`,
-      status: 'enabled',
-      installTime: Date.now(),
-      manifest: {
-        name: manifest.name || pluginName,
-        version: manifest.version || '1.0.0',
-        description: manifest.description || '',
-        author: manifest.author || '',
-        serverEntry: manifest.serverEntry || 'server/index.js',
-        clientEntry: manifest.clientEntry || 'client/index.js'
-      }
-    };
-    
-    if (existingIndex >= 0) {
-      packages[existingIndex] = packageInfo;
-      spinner3.succeed(`Plugin updated in packages.json`);
-    } else {
-      packages.push(packageInfo);
-      spinner3.succeed(`Plugin registered in packages.json`);
-    }
-    
-    // Write packages.json
-    fs.writeFileSync(packagesJsonPath, JSON.stringify(packages, null, 2) + '\n', 'utf-8');
-    
-    // Cleanup temporary files
-    if (fs.existsSync(tempOutputDir)) {
-      fs.rmSync(tempOutputDir, { recursive: true, force: true });
-    }
-    
-    // Show success message
-    console.log('\n' + chalk.green('✓ Development setup complete!\n'));
-    console.log(chalk.cyan('Plugin installed:'));
-    console.log(`  Name: ${chalk.bold(pluginName)}`);
-    console.log(`  Path: ${chalk.gray(installPath)}`);
-    console.log(`  Status: ${chalk.green('enabled')}\n`);
-    
-    console.log(chalk.cyan('Next steps:'));
-    console.log(`  1. Restart SSR server:`);
-    console.log(`     ${chalk.gray('cd packages/ssr && npx tsx src/demo/dev-server-with-pkg.tsx')}`);
-    console.log(`  2. Or use hot reload (if supported)`);
-    console.log(`  3. Test your plugin in the browser\n`);
-    
-  } catch (error) {
-    spinner1.fail('Dev workflow failed');
-    console.error(chalk.red('\nError:'), error instanceof Error ? error.message : error);
-    process.exit(1);
-  }
-}
-
-/**
- * Find extensions directory with priority:
- * 1. --target command line option
- * 2. EXTENSIONS_DIR from .env file
- * 3. Auto-detect common paths
- */
-function findExtensionsDir(projectRoot: string, envConfig: Record<string, string>): string | null {
-  // Priority 1: Environment variable from .env
-  const envExtensionsDir = envConfig.EXTENSIONS_DIR || envConfig.EXTENSIONS_PATH;
-  if (envExtensionsDir) {
-    // Resolve relative path from project root
-    const resolvedPath = path.isAbsolute(envExtensionsDir) 
-      ? envExtensionsDir 
-      : path.join(projectRoot, envExtensionsDir);
-    
-    if (fs.existsSync(resolvedPath)) {
-      return resolvedPath;
-    }
-  }
-  
-  // Priority 2: Auto-detect common paths (monorepo structure)
-  const candidates = [
-    path.join(projectRoot, '..', 'ssr', 'extensions'),
-    path.join(projectRoot, '..', '..', 'packages', 'ssr', 'extensions'),
-    path.join(projectRoot, 'packages', 'ssr', 'extensions'),
-  ];
-  
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  
-  return null;
-}
-
-/**
- * Extract .mpk file (ZIP format) to target directory
- */
-async function extractMpk(mpkPath: string, targetDir: string): Promise<void> {
-  // Use unzipper or similar library
-  // For now, use system unzip command
-  const { execSync } = await import('child_process');
-  
-  try {
-    execSync(`unzip -o "${mpkPath}" -d "${targetDir}"`, {
-      stdio: 'pipe'
-    });
-  } catch (error) {
-    throw new Error('Failed to extract .mpk file. Make sure unzip is installed.');
-  }
-}