@42ailab/42plugin 0.1.0-beta.1 → 0.1.2

package/src/validators/plugin-validator.ts

@@ -0,0 +1,635 @@
+/**
+ * 插件结构验证器
+ *
+ * 支持的插件类型：
+ * - skill: 技能插件（目录或单文件）
+ * - agent: Agent 插件（仅单文件）
+ * - command: 命令插件（目录或单文件）
+ * - hook: Hook 插件（仅目录，需要 hooks.json）
+ * - mcp: MCP 服务器插件（仅目录，需要 mcp.json）
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import matter from 'gray-matter';
+import { ValidationError } from '../errors';
+import type {
+  PluginMetadata,
+  PluginType,
+  ValidationResult,
+  ValidationIssue,
+  HookConfig,
+  McpConfig,
+} from '../types';
+
+// ============================================================================
+// 常量定义
+// ============================================================================
+
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MIN_DESCRIPTION_LENGTH = 20;
+const MAX_TAG_LENGTH = 32;
+const MAX_AGENT_FILE_SIZE = 50 * 1024; // 50KB
+
+const VALID_TYPES: PluginType[] = ['skill', 'agent', 'command', 'hook', 'mcp'];
+
+// ============================================================================
+// PluginValidator 类
+// ============================================================================
+
+export class PluginValidator {
+  /**
+   * 完整验证（返回详细结果）
+   */
+  async validateFull(pluginPath: string, overrideName?: string): Promise<ValidationResult> {
+    const result: ValidationResult = {
+      valid: true,
+      metadata: {
+        name: '',
+        type: 'skill',
+        sourcePath: '',
+      },
+      errors: [],
+      warnings: [],
+    };
+
+    const absPath = path.resolve(pluginPath);
+
+    // Phase 1: 路径检查
+    const stat = await fs.stat(absPath).catch(() => null);
+    if (!stat) {
+      result.errors.push({
+        code: 'E000',
+        message: `路径不存在: ${pluginPath}`,
+        suggestion: '请检查路径是否正确',
+      });
+      result.valid = false;
+      return result;
+    }
+
+    // Phase 2: 提取元信息并进行类型检测
+    try {
+      if (stat.isFile()) {
+        result.metadata = await this.extractFileMetadata(absPath, overrideName);
+      } else if (stat.isDirectory()) {
+        result.metadata = await this.extractDirectoryMetadata(absPath, overrideName);
+      } else {
+        result.errors.push({
+          code: 'E000',
+          message: '不支持的路径类型',
+        });
+        result.valid = false;
+        return result;
+      }
+    } catch (e) {
+      result.errors.push({
+        code: 'E000',
+        message: (e as Error).message,
+      });
+      result.valid = false;
+      return result;
+    }
+
+    // Phase 3: 通用 Schema 验证
+    this.validateSchema(result);
+
+    // Phase 4: 类型特定验证
+    await this.validateTypeSpecific(absPath, stat.isDirectory(), result);
+
+    // Phase 5: 引用检查（仅目录插件）
+    if (stat.isDirectory()) {
+      await this.validateReferences(absPath, result);
+    }
+
+    result.valid = result.errors.length === 0;
+    return result;
+  }
+
+  /**
+   * 简单验证（向后兼容）
+   */
+  async validate(pluginPath: string, overrideName?: string): Promise<PluginMetadata> {
+    const result = await this.validateFull(pluginPath, overrideName);
+
+    if (!result.valid) {
+      const firstError = result.errors[0];
+      throw new ValidationError(firstError.message, firstError.code);
+    }
+
+    return result.metadata;
+  }
+
+  // ==========================================================================
+  // 元信息提取
+  // ==========================================================================
+
+  /**
+   * 从单文件提取元信息
+   */
+  private async extractFileMetadata(
+    filePath: string,
+    overrideName?: string
+  ): Promise<PluginMetadata> {
+    const ext = path.extname(filePath).toLowerCase();
+    const basename = path.basename(filePath, ext);
+
+    if (ext !== '.md' && ext !== '.yaml' && ext !== '.yml') {
+      throw new ValidationError(
+        `不支持的文件类型: ${ext}\n支持的类型: .md, .yaml, .yml`,
+        'UNSUPPORTED_FILE_TYPE'
+      );
+    }
+
+    const content = await fs.readFile(filePath, 'utf-8');
+    const parsed = matter(content);
+    const data = parsed.data as Record<string, unknown>;
+
+    // 推断类型
+    const type = this.inferTypeFromContent(content, data);
+
+    return {
+      name: overrideName || (data.name as string) || basename,
+      type,
+      title: data.title as string | undefined,
+      description: data.description as string | undefined,
+      tags: data.tags as string[] | undefined,
+      sourcePath: filePath,
+    };
+  }
+
+  /**
+   * 从目录提取元信息
+   */
+  private async extractDirectoryMetadata(
+    dirPath: string,
+    overrideName?: string
+  ): Promise<PluginMetadata> {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+    const lowerFiles = files.map((f) => f.toLowerCase());
+    const basename = path.basename(dirPath);
+
+    // 检测插件类型（基于特征文件）
+    let type: PluginType = 'skill';
+    let frontmatterData: Record<string, unknown> = {};
+
+    // MCP: 有 mcp.json 或 .mcp.json
+    if (lowerFiles.some((f) => f === 'mcp.json' || f === '.mcp.json')) {
+      type = 'mcp';
+    }
+    // Hook: 有 hooks.json 或 hook.json
+    else if (lowerFiles.some((f) => f === 'hooks.json' || f === 'hook.json')) {
+      type = 'hook';
+    }
+    // Skill: 有 SKILL.md 或 skill.md
+    else if (lowerFiles.some((f) => f === 'skill.md')) {
+      type = 'skill';
+    }
+
+    // 尝试读取主文件获取元信息
+    const mainFiles = ['SKILL.md', 'skill.md', 'README.md', 'readme.md'];
+    let description: string | undefined;
+    let title: string | undefined;
+    let tags: string[] | undefined;
+
+    for (const file of mainFiles) {
+      if (files.includes(file)) {
+        try {
+          const content = await fs.readFile(path.join(dirPath, file), 'utf-8');
+          const parsed = matter(content);
+          frontmatterData = parsed.data as Record<string, unknown>;
+
+          if (frontmatterData.title) title = frontmatterData.title as string;
+          if (frontmatterData.description) description = frontmatterData.description as string;
+          if (frontmatterData.tags) tags = frontmatterData.tags as string[];
+          if (frontmatterData.type && VALID_TYPES.includes(frontmatterData.type as PluginType)) {
+            type = frontmatterData.type as PluginType;
+          }
+
+          // 如果没有 frontmatter 描述，取第一段文字
+          if (!description && parsed.content) {
+            const firstPara = parsed.content.trim().split('\n\n')[0];
+            if (firstPara && !firstPara.startsWith('#')) {
+              description = firstPara.slice(0, 200);
+            }
+          }
+
+          break;
+        } catch {
+          // 忽略读取错误
+        }
+      }
+    }
+
+    return {
+      name: overrideName || (frontmatterData.name as string) || basename,
+      type,
+      title,
+      description,
+      tags,
+      sourcePath: dirPath,
+    };
+  }
+
+  /**
+   * 从内容推断插件类型
+   */
+  private inferTypeFromContent(content: string, data: Record<string, unknown>): PluginType {
+    // 优先使用 frontmatter 中的 type
+    if (data.type && VALID_TYPES.includes(data.type as PluginType)) {
+      return data.type as PluginType;
+    }
+
+    // 从内容推断
+    const lowerContent = content.toLowerCase();
+
+    if (lowerContent.includes('you are') || lowerContent.includes('你是')) {
+      return 'agent';
+    }
+
+    if (lowerContent.includes('mcp') || lowerContent.includes('model context protocol')) {
+      return 'mcp';
+    }
+
+    // 默认为 skill
+    return 'skill';
+  }
+
+  // ==========================================================================
+  // Schema 验证
+  // ==========================================================================
+
+  /**
+   * 通用 Schema 验证
+   */
+  private validateSchema(result: ValidationResult): void {
+    const { metadata } = result;
+
+    // name 验证
+    if (!metadata.name) {
+      result.errors.push({
+        code: 'E001',
+        field: 'name',
+        message: '缺少必需字段: name',
+      });
+    } else {
+      // 格式验证
+      if (!NAME_PATTERN.test(metadata.name)) {
+        result.errors.push({
+          code: 'E002',
+          field: 'name',
+          message: `name "${metadata.name}" 格式无效`,
+          suggestion: '只能包含小写字母 (a-z)、数字 (0-9) 和连字符 (-)',
+        });
+      }
+
+      // 长度验证
+      if (metadata.name.length > MAX_NAME_LENGTH) {
+        result.errors.push({
+          code: 'E003',
+          field: 'name',
+          message: `name 长度超限 (${metadata.name.length}/${MAX_NAME_LENGTH})`,
+        });
+      }
+    }
+
+    // description 验证
+    if (!metadata.description) {
+      result.warnings.push({
+        code: 'W001',
+        field: 'description',
+        message: '建议添加 description 字段',
+        suggestion: '良好的描述有助于插件被发现',
+      });
+    } else {
+      if (metadata.description.length > MAX_DESCRIPTION_LENGTH) {
+        result.errors.push({
+          code: 'E020',
+          field: 'description',
+          message: `description 长度超限 (${metadata.description.length}/${MAX_DESCRIPTION_LENGTH})`,
+        });
+      } else if (metadata.description.length < MIN_DESCRIPTION_LENGTH) {
+        result.warnings.push({
+          code: 'W002',
+          field: 'description',
+          message: `description 过短 (${metadata.description.length}字符)`,
+          suggestion: '建议提供更详细的描述（至少20字符）',
+        });
+      }
+    }
+
+    // type 验证
+    if (metadata.type && !VALID_TYPES.includes(metadata.type)) {
+      result.errors.push({
+        code: 'E010',
+        field: 'type',
+        message: `无效的 type: ${metadata.type}`,
+        suggestion: `有效值: ${VALID_TYPES.join(', ')}`,
+      });
+    }
+
+    // tags 验证
+    if (metadata.tags) {
+      if (!Array.isArray(metadata.tags)) {
+        result.warnings.push({
+          code: 'W010',
+          field: 'tags',
+          message: 'tags 应该是数组格式',
+        });
+      } else {
+        for (const tag of metadata.tags) {
+          if (typeof tag !== 'string') {
+            result.warnings.push({
+              code: 'W011',
+              field: 'tags',
+              message: `tag "${tag}" 不是字符串`,
+            });
+          } else if (tag.length > MAX_TAG_LENGTH) {
+            result.warnings.push({
+              code: 'W011',
+              field: 'tags',
+              message: `tag "${tag}" 过长 (${tag.length}/${MAX_TAG_LENGTH})`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // ==========================================================================
+  // 类型特定验证
+  // ==========================================================================
+
+  /**
+   * 类型特定验证
+   */
+  private async validateTypeSpecific(
+    absPath: string,
+    isDirectory: boolean,
+    result: ValidationResult
+  ): Promise<void> {
+    const { type } = result.metadata;
+
+    switch (type) {
+      case 'agent':
+        await this.validateAgent(absPath, isDirectory, result);
+        break;
+      case 'hook':
+        await this.validateHook(absPath, isDirectory, result);
+        break;
+      case 'mcp':
+        await this.validateMcp(absPath, isDirectory, result);
+        break;
+      case 'skill':
+      case 'command':
+        // skill 和 command 支持单文件和目录，无特殊限制
+        break;
+    }
+  }
+
+  /**
+   * Agent 类型验证
+   */
+  private async validateAgent(
+    absPath: string,
+    isDirectory: boolean,
+    result: ValidationResult
+  ): Promise<void> {
+    // Agent 只支持单文件
+    if (isDirectory) {
+      result.errors.push({
+        code: 'E030',
+        field: 'type',
+        message: 'Agent 类型只支持单文件格式',
+        suggestion: '请将 Agent 内容放在单个 .md 文件中',
+      });
+      return;
+    }
+
+    // 检查文件大小
+    const stat = await fs.stat(absPath);
+    if (stat.size > MAX_AGENT_FILE_SIZE) {
+      result.warnings.push({
+        code: 'W031',
+        message: `Agent 文件过大 (${Math.round(stat.size / 1024)}KB)`,
+        suggestion: `建议 Agent 文件小于 ${MAX_AGENT_FILE_SIZE / 1024}KB`,
+      });
+    }
+
+    // 检查是否包含身份定义
+    const content = await fs.readFile(absPath, 'utf-8');
+    const lowerContent = content.toLowerCase();
+    if (!lowerContent.includes('you are') && !lowerContent.includes('你是')) {
+      result.warnings.push({
+        code: 'W030',
+        message: 'Agent 文件建议包含身份定义语句',
+        suggestion: '添加 "You are..." 或 "你是..." 来定义 Agent 身份',
+      });
+    }
+  }
+
+  /**
+   * Hook 类型验证
+   */
+  private async validateHook(
+    absPath: string,
+    isDirectory: boolean,
+    result: ValidationResult
+  ): Promise<void> {
+    // Hook 必须是目录
+    if (!isDirectory) {
+      result.errors.push({
+        code: 'E040',
+        field: 'type',
+        message: 'Hook 类型必须是目录格式',
+        suggestion: '请创建包含 hooks.json 的目录',
+      });
+      return;
+    }
+
+    // 检查 hooks.json 是否存在
+    const hooksJsonPath = path.join(absPath, 'hooks.json');
+    const hookJsonPath = path.join(absPath, 'hook.json');
+
+    let configPath: string | null = null;
+    if (await this.exists(hooksJsonPath)) {
+      configPath = hooksJsonPath;
+    } else if (await this.exists(hookJsonPath)) {
+      configPath = hookJsonPath;
+    }
+
+    if (!configPath) {
+      result.errors.push({
+        code: 'E041',
+        message: '缺少 hooks.json 配置文件',
+        suggestion: '创建 hooks.json 文件定义钩子配置',
+      });
+      return;
+    }
+
+    // 验证 hooks.json 内容
+    try {
+      const content = await fs.readFile(configPath, 'utf-8');
+      const config = JSON.parse(content) as HookConfig;
+
+      // hooks 应该是一个对象，包含事件类型作为键
+      if (!config.hooks || typeof config.hooks !== 'object') {
+        result.errors.push({
+          code: 'E042',
+          message: 'hooks 字段为空或格式无效',
+          suggestion: '在 hooks.json 中定义 hooks 对象，包含事件类型作为键',
+        });
+      } else {
+        // 检查是否至少有一个事件类型定义
+        const eventTypes = Object.keys(config.hooks);
+        if (eventTypes.length === 0) {
+          result.errors.push({
+            code: 'E042',
+            message: 'hooks 对象为空',
+            suggestion: '在 hooks.json 中定义至少一个事件类型（如 PreToolUse, PostToolUse 等）',
+          });
+        }
+      }
+    } catch (e) {
+      result.errors.push({
+        code: 'E041',
+        message: `hooks.json 解析失败: ${(e as Error).message}`,
+        suggestion: '请检查 JSON 格式是否正确',
+      });
+    }
+  }
+
+  /**
+   * MCP 类型验证
+   */
+  private async validateMcp(
+    absPath: string,
+    isDirectory: boolean,
+    result: ValidationResult
+  ): Promise<void> {
+    // MCP 必须是目录
+    if (!isDirectory) {
+      result.errors.push({
+        code: 'E050',
+        field: 'type',
+        message: 'MCP 类型必须是目录格式',
+        suggestion: '请创建包含 mcp.json 的目录',
+      });
+      return;
+    }
+
+    // 检查 mcp.json 是否存在
+    const mcpJsonPath = path.join(absPath, 'mcp.json');
+    const dotMcpJsonPath = path.join(absPath, '.mcp.json');
+
+    let configPath: string | null = null;
+    if (await this.exists(mcpJsonPath)) {
+      configPath = mcpJsonPath;
+    } else if (await this.exists(dotMcpJsonPath)) {
+      configPath = dotMcpJsonPath;
+    }
+
+    if (!configPath) {
+      result.errors.push({
+        code: 'E051',
+        message: '缺少 mcp.json 配置文件',
+        suggestion: '创建 mcp.json 文件定义 MCP 服务器配置',
+      });
+      return;
+    }
+
+    // 验证 mcp.json 内容
+    try {
+      const content = await fs.readFile(configPath, 'utf-8');
+      const config = JSON.parse(content) as McpConfig;
+
+      // 建议指定 protocol_version
+      if (!config.protocol_version) {
+        result.warnings.push({
+          code: 'W050',
+          message: '建议指定 protocol_version',
+          suggestion: '添加 "protocol_version": "2024-11" 到 mcp.json',
+        });
+      }
+
+      // 建议声明 capabilities
+      if (!config.capabilities) {
+        result.warnings.push({
+          code: 'W051',
+          message: '建议声明 capabilities',
+          suggestion: '添加 capabilities 对象声明支持的功能',
+        });
+      }
+    } catch (e) {
+      result.errors.push({
+        code: 'E051',
+        message: `mcp.json 解析失败: ${(e as Error).message}`,
+        suggestion: '请检查 JSON 格式是否正确',
+      });
+    }
+  }
+
+  // ==========================================================================
+  // 引用检查
+  // ==========================================================================
+
+  /**
+   * 引用文件检查
+   */
+  private async validateReferences(dirPath: string, result: ValidationResult): Promise<void> {
+    // 读取主文件内容
+    const mainFiles = ['SKILL.md', 'skill.md', 'README.md'];
+    let content = '';
+
+    for (const file of mainFiles) {
+      try {
+        content = await fs.readFile(path.join(dirPath, file), 'utf-8');
+        break;
+      } catch {
+        // 继续尝试下一个文件
+      }
+    }
+
+    if (!content) return;
+
+    // 提取引用
+    const patterns = [/scripts\/[\w\-\.\/]+/g, /references\/[\w\-\.\/]+/g, /assets\/[\w\-\.\/]+/g];
+
+    const refs = new Set<string>();
+    for (const pattern of patterns) {
+      const matches = content.match(pattern);
+      if (matches) {
+        matches.forEach((m) => refs.add(m));
+      }
+    }
+
+    // 检查引用是否存在
+    for (const ref of refs) {
+      const refPath = path.join(dirPath, ref);
+      const exists = await this.exists(refPath);
+
+      if (!exists) {
+        result.errors.push({
+          code: 'E100',
+          message: `引用文件不存在: ${ref}`,
+          suggestion: `创建文件 ${ref} 或从文档中移除引用`,
+        });
+      }
+    }
+  }
+
+  // ==========================================================================
+  // 辅助方法
+  // ==========================================================================
+
+  private async exists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/commands/version.ts

@@ -1,20 +0,0 @@
-import { Command } from 'commander';
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-export const versionCommand = new Command('version')
-  .description('显示版本信息')
-  .action(() => {
-    // Try to read version from package.json
-    try {
-      // Get the directory of the current module
-      const __dirname = path.dirname(fileURLToPath(import.meta.url));
-      const pkgPath = path.resolve(__dirname, '../../package.json');
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-      console.log(`42plugin CLI v${pkg.version}`);
-    } catch {
-      // Fallback if package.json is not readable
-      console.log('42plugin CLI v0.1.0');
-    }
-  });