@within-7/minto 0.0.5-dev.1

package/dist/utils/pluginValidator.js

@@ -0,0 +1,774 @@
+import fs from "fs";
+import path from "path";
+import matter from "gray-matter";
+import semver from "semver";
+import { z } from "zod";
+import { PluginManifestSchema } from "../types/plugin.js";
+const AgentFrontmatterSchema = z.object({
+  name: z.string().min(1, "Agent name is required"),
+  description: z.string().min(1, "Agent description is required"),
+  tools: z.union([
+    z.string(),
+    // "*" for all tools
+    z.array(z.string()).min(1, "At least one tool must be specified")
+  ]).optional(),
+  model: z.string().optional()
+});
+const CommandFrontmatterSchema = z.object({
+  name: z.string().min(1, "Command name is required"),
+  description: z.string().optional(),
+  aliases: z.array(z.string()).optional(),
+  enabled: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  progressMessage: z.string().optional(),
+  argNames: z.array(z.string()).optional(),
+  "allowed-tools": z.array(z.string()).optional()
+});
+const SkillFrontmatterSchema = z.object({
+  name: z.string().min(1, "Skill name is required"),
+  description: z.string().min(1, "Skill description is required")
+});
+const HookConfigSchema = z.object({
+  event: z.enum([
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "SessionStart",
+    "SessionEnd",
+    "Stop",
+    "SubagentStop",
+    "Notification",
+    "PreCompact"
+  ]),
+  matcher: z.string().optional(),
+  type: z.enum(["command", "message", "notification"]),
+  command: z.string().optional(),
+  message: z.string().optional(),
+  blocking: z.boolean().optional(),
+  timeout: z.number().optional()
+});
+const MCPServerConfigSchema = z.object({
+  command: z.string().min(1, "MCP server command is required"),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string()).optional(),
+  timeout: z.number().optional()
+});
+async function validatePlugin(pluginPath) {
+  const errors = [];
+  const warnings = [];
+  if (!fs.existsSync(pluginPath)) {
+    return {
+      valid: false,
+      errors: [{
+        type: "manifest",
+        message: `Plugin directory does not exist: ${pluginPath}`
+      }],
+      warnings: []
+    };
+  }
+  const stats = fs.statSync(pluginPath);
+  if (!stats.isDirectory()) {
+    return {
+      valid: false,
+      errors: [{
+        type: "manifest",
+        message: `Plugin path is not a directory: ${pluginPath}`
+      }],
+      warnings: []
+    };
+  }
+  const manifestPath = path.join(pluginPath, "plugin.json");
+  if (!fs.existsSync(manifestPath)) {
+    return {
+      valid: false,
+      errors: [{
+        type: "manifest",
+        file: "plugin.json",
+        message: "Plugin manifest (plugin.json) not found"
+      }],
+      warnings: []
+    };
+  }
+  let manifest;
+  try {
+    const manifestContent = fs.readFileSync(manifestPath, "utf-8");
+    const manifestData = JSON.parse(manifestContent);
+    const manifestResult = validateManifest(manifestData);
+    errors.push(...manifestResult.errors);
+    warnings.push(...manifestResult.warnings);
+    if (!manifestResult.valid) {
+      return { valid: false, errors, warnings };
+    }
+    manifest = manifestData;
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [{
+        type: "manifest",
+        file: "plugin.json",
+        message: `Failed to parse manifest: ${error instanceof Error ? error.message : String(error)}`,
+        details: error
+      }],
+      warnings: []
+    };
+  }
+  if (manifest.engines) {
+    const engineResult = await validateEngines(manifest.engines);
+    errors.push(...engineResult.errors);
+    warnings.push(...engineResult.warnings);
+  }
+  if (manifest.agents && manifest.agents.length > 0) {
+    for (const agentFile of manifest.agents) {
+      const agentPath = path.join(pluginPath, agentFile);
+      const result = validateAgentFile(agentPath);
+      errors.push(...result.errors);
+      warnings.push(...result.warnings);
+    }
+  }
+  if (manifest.commands && manifest.commands.length > 0) {
+    for (const commandFile of manifest.commands) {
+      const commandPath = path.join(pluginPath, commandFile);
+      const result = validateCommandFile(commandPath);
+      errors.push(...result.errors);
+      warnings.push(...result.warnings);
+    }
+  }
+  if (manifest.skills && manifest.skills.length > 0) {
+    for (const skillFile of manifest.skills) {
+      const skillPath = path.join(pluginPath, skillFile);
+      const result = validateSkillFile(skillPath);
+      errors.push(...result.errors);
+      warnings.push(...result.warnings);
+    }
+  }
+  if (manifest.hooks && manifest.hooks.length > 0) {
+    for (const hookFile of manifest.hooks) {
+      const hookPath = path.join(pluginPath, hookFile);
+      const result = validateHookFile(hookPath);
+      errors.push(...result.errors);
+      warnings.push(...result.warnings);
+    }
+  }
+  if (manifest.mcpServers && manifest.mcpServers.length > 0) {
+    for (const mcpFile of manifest.mcpServers) {
+      const mcpPath = path.join(pluginPath, mcpFile);
+      const result = validateMCPServerFile(mcpPath);
+      errors.push(...result.errors);
+      warnings.push(...result.warnings);
+    }
+  }
+  const componentFiles = /* @__PURE__ */ new Set([
+    ...manifest.agents || [],
+    ...manifest.commands || [],
+    ...manifest.skills || [],
+    ...manifest.hooks || [],
+    ...manifest.mcpServers || []
+  ]);
+  if (componentFiles.size === 0) {
+    warnings.push({
+      type: "manifest",
+      message: "Plugin has no components (agents, commands, skills, hooks, or MCP servers)"
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateManifest(manifest) {
+  const errors = [];
+  const warnings = [];
+  if (!manifest || typeof manifest !== "object") {
+    return {
+      valid: false,
+      errors: [{
+        type: "manifest",
+        message: "Manifest must be a valid JSON object"
+      }],
+      warnings: []
+    };
+  }
+  try {
+    PluginManifestSchema.parse(manifest);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      for (const issue of error.errors) {
+        errors.push({
+          type: "manifest",
+          message: `${issue.path.join(".")}: ${issue.message}`,
+          details: issue
+        });
+      }
+    } else {
+      errors.push({
+        type: "manifest",
+        message: `Manifest validation failed: ${error instanceof Error ? error.message : String(error)}`,
+        details: error
+      });
+    }
+  }
+  if (manifest.name && !/^[a-z0-9-]+$/.test(manifest.name)) {
+    errors.push({
+      type: "manifest",
+      message: "Plugin name must be lowercase alphanumeric with hyphens only",
+      details: { name: manifest.name }
+    });
+  }
+  if (manifest.version && !semver.valid(manifest.version)) {
+    errors.push({
+      type: "manifest",
+      message: `Invalid version format: ${manifest.version}. Must follow semver (e.g., 1.0.0)`,
+      details: { version: manifest.version }
+    });
+  }
+  if (manifest.homepage) {
+    try {
+      new URL(manifest.homepage);
+    } catch {
+      errors.push({
+        type: "manifest",
+        message: `Invalid homepage URL: ${manifest.homepage}`
+      });
+    }
+  }
+  if (manifest.repository) {
+    try {
+      new URL(manifest.repository);
+    } catch {
+      errors.push({
+        type: "manifest",
+        message: `Invalid repository URL: ${manifest.repository}`
+      });
+    }
+  }
+  if (!manifest.description) {
+    warnings.push({
+      type: "manifest",
+      message: "Missing recommended field: description"
+    });
+  }
+  if (!manifest.author) {
+    warnings.push({
+      type: "manifest",
+      message: "Missing recommended field: author"
+    });
+  }
+  if (!manifest.license) {
+    warnings.push({
+      type: "manifest",
+      message: "Missing recommended field: license"
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+async function validateEngines(engines) {
+  const errors = [];
+  const warnings = [];
+  if (engines.minto) {
+    const validRange = semver.validRange(engines.minto);
+    if (!validRange) {
+      errors.push({
+        type: "engine",
+        message: `Invalid minto version range: ${engines.minto}`,
+        details: { engine: "minto", range: engines.minto }
+      });
+    } else {
+      try {
+        const { VERSION } = await import("../version.js");
+        if (!semver.satisfies(VERSION, engines.minto)) {
+          warnings.push({
+            type: "engine",
+            message: `Plugin requires minto ${engines.minto}, but current version is ${VERSION}`
+          });
+        }
+      } catch {
+      }
+    }
+  }
+  if (engines.node) {
+    const validRange = semver.validRange(engines.node);
+    if (!validRange) {
+      errors.push({
+        type: "engine",
+        message: `Invalid node version range: ${engines.node}`,
+        details: { engine: "node", range: engines.node }
+      });
+    } else {
+      if (!semver.satisfies(process.version, engines.node)) {
+        warnings.push({
+          type: "engine",
+          message: `Plugin requires node ${engines.node}, but current version is ${process.version}`
+        });
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateAgentFile(filePath) {
+  const errors = [];
+  const warnings = [];
+  if (!fs.existsSync(filePath)) {
+    return {
+      valid: false,
+      errors: [{
+        type: "agent",
+        file: filePath,
+        message: `Agent file not found: ${filePath}`
+      }],
+      warnings: []
+    };
+  }
+  const ext = path.extname(filePath);
+  if (ext !== ".md" && ext !== ".markdown") {
+    warnings.push({
+      type: "agent",
+      file: filePath,
+      message: `Agent file should have .md or .markdown extension, got: ${ext}`
+    });
+  }
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsed = matter(content);
+    if (!parsed.data || Object.keys(parsed.data).length === 0) {
+      errors.push({
+        type: "agent",
+        file: filePath,
+        message: "Agent file must have YAML frontmatter"
+      });
+      return { valid: false, errors, warnings };
+    }
+    try {
+      AgentFrontmatterSchema.parse(parsed.data);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        for (const issue of error.errors) {
+          errors.push({
+            type: "agent",
+            file: filePath,
+            message: `Frontmatter ${issue.path.join(".")}: ${issue.message}`,
+            details: issue
+          });
+        }
+      }
+    }
+    if (!parsed.content || parsed.content.trim().length === 0) {
+      warnings.push({
+        type: "agent",
+        file: filePath,
+        message: "Agent file has no content after frontmatter"
+      });
+    }
+    if (parsed.data.tools) {
+      if (Array.isArray(parsed.data.tools)) {
+        if (parsed.data.tools.length === 0) {
+          errors.push({
+            type: "agent",
+            file: filePath,
+            message: 'Tools array cannot be empty (use "*" for all tools or omit the field)'
+          });
+        }
+      } else if (parsed.data.tools !== "*") {
+        errors.push({
+          type: "agent",
+          file: filePath,
+          message: 'Tools must be an array of tool names or "*" for all tools',
+          details: { tools: parsed.data.tools }
+        });
+      }
+    }
+  } catch (error) {
+    errors.push({
+      type: "agent",
+      file: filePath,
+      message: `Failed to parse agent file: ${error instanceof Error ? error.message : String(error)}`,
+      details: error
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateCommandFile(filePath) {
+  const errors = [];
+  const warnings = [];
+  if (!fs.existsSync(filePath)) {
+    return {
+      valid: false,
+      errors: [{
+        type: "command",
+        file: filePath,
+        message: `Command file not found: ${filePath}`
+      }],
+      warnings: []
+    };
+  }
+  const ext = path.extname(filePath);
+  if (ext !== ".md" && ext !== ".markdown") {
+    warnings.push({
+      type: "command",
+      file: filePath,
+      message: `Command file should have .md or .markdown extension, got: ${ext}`
+    });
+  }
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsed = matter(content);
+    if (!parsed.data || Object.keys(parsed.data).length === 0) {
+      errors.push({
+        type: "command",
+        file: filePath,
+        message: "Command file must have YAML frontmatter"
+      });
+      return { valid: false, errors, warnings };
+    }
+    try {
+      CommandFrontmatterSchema.parse(parsed.data);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        for (const issue of error.errors) {
+          errors.push({
+            type: "command",
+            file: filePath,
+            message: `Frontmatter ${issue.path.join(".")}: ${issue.message}`,
+            details: issue
+          });
+        }
+      }
+    }
+    if (!parsed.content || parsed.content.trim().length === 0) {
+      warnings.push({
+        type: "command",
+        file: filePath,
+        message: "Command file has no content after frontmatter"
+      });
+    }
+    const filename = path.basename(filePath, path.extname(filePath));
+    if (parsed.data.name && parsed.data.name !== filename) {
+      warnings.push({
+        type: "command",
+        file: filePath,
+        message: `Command name "${parsed.data.name}" does not match filename "${filename}"`
+      });
+    }
+  } catch (error) {
+    errors.push({
+      type: "command",
+      file: filePath,
+      message: `Failed to parse command file: ${error instanceof Error ? error.message : String(error)}`,
+      details: error
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateSkillFile(filePath) {
+  const errors = [];
+  const warnings = [];
+  if (!fs.existsSync(filePath)) {
+    return {
+      valid: false,
+      errors: [{
+        type: "skill",
+        file: filePath,
+        message: `Skill file not found: ${filePath}`
+      }],
+      warnings: []
+    };
+  }
+  const ext = path.extname(filePath);
+  if (ext !== ".md" && ext !== ".markdown") {
+    warnings.push({
+      type: "skill",
+      file: filePath,
+      message: `Skill file should have .md or .markdown extension, got: ${ext}`
+    });
+  }
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsed = matter(content);
+    if (!parsed.data || Object.keys(parsed.data).length === 0) {
+      errors.push({
+        type: "skill",
+        file: filePath,
+        message: "Skill file must have YAML frontmatter"
+      });
+      return { valid: false, errors, warnings };
+    }
+    try {
+      SkillFrontmatterSchema.parse(parsed.data);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        for (const issue of error.errors) {
+          errors.push({
+            type: "skill",
+            file: filePath,
+            message: `Frontmatter ${issue.path.join(".")}: ${issue.message}`,
+            details: issue
+          });
+        }
+      }
+    }
+    if (!parsed.content || parsed.content.trim().length === 0) {
+      warnings.push({
+        type: "skill",
+        file: filePath,
+        message: "Skill file has no content after frontmatter"
+      });
+    }
+  } catch (error) {
+    errors.push({
+      type: "skill",
+      file: filePath,
+      message: `Failed to parse skill file: ${error instanceof Error ? error.message : String(error)}`,
+      details: error
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateHookFile(filePath) {
+  const errors = [];
+  const warnings = [];
+  if (!fs.existsSync(filePath)) {
+    return {
+      valid: false,
+      errors: [{
+        type: "hook",
+        file: filePath,
+        message: `Hook file not found: ${filePath}`
+      }],
+      warnings: []
+    };
+  }
+  const ext = path.extname(filePath);
+  const validExtensions = [".js", ".mjs", ".ts", ".tsx", ".json"];
+  if (!validExtensions.includes(ext)) {
+    errors.push({
+      type: "hook",
+      file: filePath,
+      message: `Hook file must have extension: ${validExtensions.join(", ")}. Got: ${ext}`
+    });
+    return { valid: false, errors, warnings };
+  }
+  if (ext === ".json") {
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      const config = JSON.parse(content);
+      try {
+        HookConfigSchema.parse(config);
+      } catch (error) {
+        if (error instanceof z.ZodError) {
+          for (const issue of error.errors) {
+            errors.push({
+              type: "hook",
+              file: filePath,
+              message: `Hook config ${issue.path.join(".")}: ${issue.message}`,
+              details: issue
+            });
+          }
+        }
+      }
+      if (config.type === "command" && !config.command) {
+        errors.push({
+          type: "hook",
+          file: filePath,
+          message: 'Hook type "command" requires a "command" field'
+        });
+      }
+      if (config.type === "message" && !config.message) {
+        errors.push({
+          type: "hook",
+          file: filePath,
+          message: 'Hook type "message" requires a "message" field'
+        });
+      }
+    } catch (error) {
+      errors.push({
+        type: "hook",
+        file: filePath,
+        message: `Failed to parse hook config: ${error instanceof Error ? error.message : String(error)}`,
+        details: error
+      });
+    }
+  } else {
+    try {
+      fs.readFileSync(filePath, "utf-8");
+    } catch (error) {
+      errors.push({
+        type: "hook",
+        file: filePath,
+        message: `Failed to read hook file: ${error instanceof Error ? error.message : String(error)}`,
+        details: error
+      });
+    }
+    warnings.push({
+      type: "hook",
+      file: filePath,
+      message: "JavaScript/TypeScript hooks will be validated at runtime"
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateMCPServerFile(filePath) {
+  const errors = [];
+  const warnings = [];
+  if (!fs.existsSync(filePath)) {
+    return {
+      valid: false,
+      errors: [{
+        type: "mcp",
+        file: filePath,
+        message: `MCP server config file not found: ${filePath}`
+      }],
+      warnings: []
+    };
+  }
+  const ext = path.extname(filePath);
+  if (ext !== ".json") {
+    errors.push({
+      type: "mcp",
+      file: filePath,
+      message: `MCP server config must be a JSON file, got: ${ext}`
+    });
+    return { valid: false, errors, warnings };
+  }
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const config = JSON.parse(content);
+    try {
+      MCPServerConfigSchema.parse(config);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        for (const issue of error.errors) {
+          errors.push({
+            type: "mcp",
+            file: filePath,
+            message: `MCP config ${issue.path.join(".")}: ${issue.message}`,
+            details: issue
+          });
+        }
+      }
+    }
+    if (config.command && config.command.trim().length === 0) {
+      errors.push({
+        type: "mcp",
+        file: filePath,
+        message: "MCP server command cannot be empty"
+      });
+    }
+    if (config.timeout && config.timeout < 1e3) {
+      warnings.push({
+        type: "mcp",
+        file: filePath,
+        message: `MCP server timeout is very low (${config.timeout}ms), consider increasing`
+      });
+    }
+  } catch (error) {
+    errors.push({
+      type: "mcp",
+      file: filePath,
+      message: `Failed to parse MCP server config: ${error instanceof Error ? error.message : String(error)}`,
+      details: error
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateDependencies(dependencies, installedPackages) {
+  const errors = [];
+  const warnings = [];
+  for (const [pkg, version] of Object.entries(dependencies)) {
+    const validRange = semver.validRange(version);
+    if (!validRange) {
+      errors.push({
+        type: "dependency",
+        message: `Invalid version range for ${pkg}: ${version}`,
+        details: { package: pkg, version }
+      });
+    }
+    if (installedPackages && !installedPackages.has(pkg)) {
+      warnings.push({
+        type: "dependency",
+        message: `Dependency not installed: ${pkg}@${version}`
+      });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+async function validatePlugins(pluginPaths) {
+  const results = /* @__PURE__ */ new Map();
+  await Promise.all(
+    pluginPaths.map(async (pluginPath) => {
+      const result = await validatePlugin(pluginPath);
+      results.set(pluginPath, result);
+    })
+  );
+  return results;
+}
+function formatValidationResult(result, pluginName) {
+  const lines = [];
+  if (pluginName) {
+    lines.push(`Plugin: ${pluginName}`);
+  }
+  if (result.valid) {
+    lines.push("\u2713 Validation passed");
+  } else {
+    lines.push(`\u2717 Validation failed with ${result.errors.length} error(s)`);
+  }
+  if (result.errors.length > 0) {
+    lines.push("\nErrors:");
+    for (const error of result.errors) {
+      const location = error.file ? ` (${error.file})` : "";
+      lines.push(`  \u2022 [${error.type}]${location} ${error.message}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push("\nWarnings:");
+    for (const warning of result.warnings) {
+      const location = warning.file ? ` (${warning.file})` : "";
+      lines.push(`  \u2022 [${warning.type}]${location} ${warning.message}`);
+    }
+  }
+  return lines.join("\n");
+}
+export {
+  formatValidationResult,
+  validateAgentFile,
+  validateCommandFile,
+  validateDependencies,
+  validateHookFile,
+  validateMCPServerFile,
+  validateManifest,
+  validatePlugin,
+  validatePlugins,
+  validateSkillFile
+};
+//# sourceMappingURL=pluginValidator.js.map