@vibecheckai/cli 3.5.0 → 3.5.2

package/mcp-server/handlers/tool-handler.ts

@@ -0,0 +1,554 @@
+/**
+ * Universal Tool Handler
+ * 
+ * Registry-driven dispatcher for all MCP tools.
+ * 
+ * Pipeline:
+ * 1) Load tool definition from registry
+ * 2) Validate input schema
+ * 3) Sandbox path validation
+ * 4) Execute CLI command
+ * 5) Parse output into canonical JSON
+ * 6) Validate output schema
+ * 7) Return response with error envelope
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import Ajv from "ajv";
+import type {
+  RunRequest,
+  RunResponse,
+  ErrorEnvelope,
+  ErrorCode,
+  ToolDefinition,
+  ToolResult,
+  ValidationError,
+  Finding,
+} from "../lib/types";
+import { PathSandbox } from "../lib/sandbox";
+import { CliExecutor, parseCliOutput, sortFindings, buildCliArgs } from "../lib/executor";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REGISTRY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+interface ToolRegistry {
+  version: string;
+  tools: Record<string, ToolDefinition>;
+  $defs?: Record<string, unknown>;
+}
+
+let registryCache: ToolRegistry | null = null;
+
+/**
+ * Load tool registry (cached)
+ */
+function loadRegistry(): ToolRegistry {
+  if (registryCache) return registryCache;
+
+  const registryPath = path.join(__dirname, "../registry/tools.json");
+  const content = fs.readFileSync(registryPath, "utf-8");
+  registryCache = JSON.parse(content) as ToolRegistry;
+  return registryCache;
+}
+
+/**
+ * Get tool definition by name (supports aliases)
+ */
+function getToolDefinition(toolName: string): ToolDefinition | null {
+  const registry = loadRegistry();
+
+  // Direct match
+  if (registry.tools[toolName]) {
+    return registry.tools[toolName];
+  }
+
+  // Search aliases
+  for (const tool of Object.values(registry.tools)) {
+    if (tool.aliases?.includes(toolName)) {
+      return tool;
+    }
+  }
+
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+/**
+ * Validate data against JSON schema
+ */
+function validateSchema(
+  data: unknown,
+  schema: unknown,
+  schemaName: string
+): ValidationError[] {
+  const validate = ajv.compile(schema as object);
+  const valid = validate(data);
+
+  if (valid) return [];
+
+  return (validate.errors || []).map((err) => ({
+    path: err.instancePath || "/",
+    message: err.message || "Validation failed",
+    expected: err.params?.allowedValues?.join(", "),
+    actual: String(err.data),
+  }));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ERROR HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const ERROR_NEXT_STEPS: Record<ErrorCode, string[]> = {
+  INPUT_VALIDATION: [
+    "Check the tool's inputSchema for required fields",
+    "Ensure all values match expected types",
+    "Review the validation errors for specifics",
+  ],
+  TOOL_NOT_FOUND: [
+    "Check the tool name is spelled correctly",
+    "Use 'vibecheck.scan' format for tool names",
+    "List available tools with the registry",
+  ],
+  TIER_REQUIRED: [
+    "This tool requires a Pro subscription ($69/mo)",
+    "Upgrade at https://vibecheckai.dev/pricing",
+    "Some tools have free alternatives",
+  ],
+  NOT_ENTITLED: [
+    "This tool requires a Pro subscription ($69/mo)",
+    "Upgrade at https://vibecheckai.dev/pricing",
+    "Run: vibecheck upgrade",
+  ],
+  OPTION_NOT_ENTITLED: [
+    "This option requires a Pro subscription ($69/mo)",
+    "The base tool is available on FREE tier",
+    "Upgrade at https://vibecheckai.dev/pricing",
+  ],
+  PATH_VIOLATION: [
+    "Ensure paths are within the project directory",
+    "Do not use absolute paths or path traversal (..)",
+    "Check for symlinks pointing outside the project",
+  ],
+  EXECUTOR_FAILED: [
+    "Check the CLI command output for details",
+    "Run 'vibecheck doctor' to diagnose issues",
+    "Ensure dependencies are installed",
+  ],
+  OUTPUT_PARSE_ERROR: [
+    "The CLI output was not valid JSON",
+    "This may indicate a CLI bug",
+    "Try running the command directly for debugging",
+  ],
+  OUTPUT_VALIDATION: [
+    "The CLI output didn't match expected schema",
+    "This may indicate a version mismatch",
+    "Please report this issue",
+  ],
+  TIMEOUT: [
+    "The command timed out",
+    "Try a smaller scope (fewer files/categories)",
+    "Increase timeout if running intensive operations",
+  ],
+  INTERNAL_ERROR: [
+    "An unexpected error occurred",
+    "Please report this issue with the requestId",
+    "https://github.com/vibecheckai/vibecheck/issues",
+  ],
+  INVALID_API_KEY: [
+    "The API key is invalid or expired",
+    "Run: vibecheck login",
+    "Check your credentials at https://vibecheckai.dev/dashboard",
+  ],
+  RATE_LIMITED: [
+    "Too many requests - please wait and try again",
+    "Consider upgrading for higher limits",
+    "https://vibecheckai.dev/pricing",
+  ],
+};
+
+function createErrorEnvelope(
+  code: ErrorCode,
+  message: string,
+  requestId: string,
+  extra?: Partial<ErrorEnvelope>
+): ErrorEnvelope {
+  return {
+    code,
+    message,
+    nextSteps: ERROR_NEXT_STEPS[code],
+    requestId,
+    ...extra,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN HANDLER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Handle a tool execution request
+ */
+export async function handleToolRequest(request: RunRequest): Promise<RunResponse> {
+  const startedAt = new Date().toISOString();
+  const startTime = Date.now();
+
+  const baseMetadata = {
+    startedAt,
+    completedAt: "",
+    durationMs: 0,
+    tool: request.tool,
+  };
+
+  try {
+    // 1) Load tool definition
+    const toolDef = getToolDefinition(request.tool);
+    if (!toolDef) {
+      return buildErrorResponse(
+        request,
+        createErrorEnvelope("TOOL_NOT_FOUND", `Unknown tool: ${request.tool}`, request.requestId),
+        baseMetadata,
+        startTime
+      );
+    }
+
+    // 2) Check tier access (aligned with CLI entitlements-v2.js)
+    const userTier = request.context?.tier || "free";
+    
+    // Developer mode bypass (blocked in production environments)
+    const isDevProBypassAllowed = (): boolean => {
+      if (process.env.NODE_ENV === "production") return false;
+      if (process.env.CI === "true" || process.env.CI === "1") return false;
+      return process.env.VIBECHECK_DEV_PRO === "1";
+    };
+    const isDevMode = isDevProBypassAllowed();
+    
+    if (toolDef.tier === "pro" && userTier !== "pro" && !isDevMode) {
+      return buildErrorResponse(
+        request,
+        createErrorEnvelope(
+          "NOT_ENTITLED",
+          "Requires PRO",
+          request.requestId,
+          {
+            userAction: "Open billing",
+            retryable: false,
+            tier: userTier,
+            required: "pro",
+            tool: toolDef.name,
+            upgradeUrl: "https://vibecheckai.dev/pricing",
+          }
+        ),
+        baseMetadata,
+        startTime
+      );
+    }
+
+    // 3) Validate input schema
+    const inputErrors = validateSchema(request.args, toolDef.inputSchema, "input");
+    if (inputErrors.length > 0) {
+      return buildErrorResponse(
+        request,
+        createErrorEnvelope(
+          "INPUT_VALIDATION",
+          "Input validation failed",
+          request.requestId,
+          { validationErrors: inputErrors }
+        ),
+        baseMetadata,
+        startTime
+      );
+    }
+
+    // 4) Resolve and sandbox project path
+    const projectPath = String(request.args.projectPath || request.context?.projectRoot || ".");
+    let sandbox: PathSandbox;
+    let resolvedProjectPath: string;
+
+    try {
+      // Determine project root (use provided or current working directory)
+      const baseProjectRoot = request.context?.projectRoot || process.cwd();
+      sandbox = new PathSandbox({ projectRoot: baseProjectRoot });
+      resolvedProjectPath = sandbox.assertAllowed(projectPath);
+    } catch (err) {
+      const error = err as Error & { violationType?: string };
+      return buildErrorResponse(
+        request,
+        createErrorEnvelope(
+          "PATH_VIOLATION",
+          error.message,
+          request.requestId,
+          { receipt: `violation: ${error.violationType}` }
+        ),
+        baseMetadata,
+        startTime
+      );
+    }
+
+    // Validate any other path arguments
+    const pathArgs = ["outputPath", "file", "filePath"];
+    for (const argName of pathArgs) {
+      const argValue = request.args[argName];
+      if (argValue && typeof argValue === "string") {
+        const result = sandbox.validate(argValue);
+        if (!result.allowed) {
+          return buildErrorResponse(
+            request,
+            createErrorEnvelope(
+              "PATH_VIOLATION",
+              `Invalid path in '${argName}': ${result.error}`,
+              request.requestId
+            ),
+            baseMetadata,
+            startTime
+          );
+        }
+      }
+    }
+
+    // 5) Build CLI arguments
+    const cliArgs = buildCliArgs(
+      { ...request.args, projectPath: resolvedProjectPath },
+      toolDef.cli.argMap,
+      toolDef.cli.fixedFlags
+    );
+
+    // 6) Execute CLI command
+    const executor = new CliExecutor({
+      cwd: resolvedProjectPath,
+      timeoutMs: toolDef.cli.timeoutMs || 300000,
+      requestId: request.requestId,
+      traceId: request.traceId,
+    });
+
+    const execResult = await executor.execute(toolDef.cli.command, cliArgs);
+
+    // Check for timeout
+    if (execResult.timedOut) {
+      return buildErrorResponse(
+        request,
+        createErrorEnvelope(
+          "TIMEOUT",
+          `Command timed out after ${toolDef.cli.timeoutMs}ms`,
+          request.requestId
+        ),
+        {
+          ...baseMetadata,
+          cliCommand: `vibecheck ${toolDef.cli.command}`,
+          exitCode: execResult.exitCode,
+        },
+        startTime
+      );
+    }
+
+    // Check for execution failure (exit code > 2 indicates error, not just findings)
+    if (execResult.exitCode > 10) {
+      return buildErrorResponse(
+        request,
+        createErrorEnvelope(
+          "EXECUTOR_FAILED",
+          execResult.stderr || `CLI exited with code ${execResult.exitCode}`,
+          request.requestId,
+          { receipt: `exit_code: ${execResult.exitCode}` }
+        ),
+        {
+          ...baseMetadata,
+          cliCommand: `vibecheck ${toolDef.cli.command}`,
+          exitCode: execResult.exitCode,
+        },
+        startTime
+      );
+    }
+
+    // 7) Parse CLI output
+    let toolResult: ToolResult;
+    try {
+      toolResult = parseCliOutput(execResult.stdout, execResult.stderr);
+    } catch (err) {
+      return buildErrorResponse(
+        request,
+        createErrorEnvelope(
+          "OUTPUT_PARSE_ERROR",
+          `Failed to parse CLI output: ${(err as Error).message}`,
+          request.requestId
+        ),
+        {
+          ...baseMetadata,
+          cliCommand: `vibecheck ${toolDef.cli.command}`,
+          exitCode: execResult.exitCode,
+        },
+        startTime
+      );
+    }
+
+    // 8) Sort findings for stable output
+    if (toolResult.findings) {
+      toolResult.findings = sortFindings(toolResult.findings);
+    }
+
+    // 9) Validate output schema (soft validation - log but don't fail)
+    const outputErrors = validateSchema(toolResult, toolDef.outputSchema, "output");
+    if (outputErrors.length > 0) {
+      // Log but don't fail - output schema validation is informational
+      console.error(
+        `[WARN] Output schema validation errors for ${toolDef.name}:`,
+        JSON.stringify(outputErrors)
+      );
+    }
+
+    // 10) Build success response
+    const completedAt = new Date().toISOString();
+    return {
+      requestId: request.requestId,
+      traceId: request.traceId,
+      ok: true,
+      data: toolResult,
+      metadata: {
+        startedAt,
+        completedAt,
+        durationMs: Date.now() - startTime,
+        tool: toolDef.name,
+        cliCommand: `vibecheck ${toolDef.cli.command}`,
+        exitCode: execResult.exitCode,
+      },
+    };
+  } catch (err) {
+    // Catch-all for unexpected errors
+    const error = err as Error;
+    return buildErrorResponse(
+      request,
+      createErrorEnvelope(
+        "INTERNAL_ERROR",
+        "An unexpected error occurred",
+        request.requestId,
+        { receipt: error.message }
+      ),
+      baseMetadata,
+      startTime
+    );
+  }
+}
+
+/**
+ * Build error response
+ */
+function buildErrorResponse(
+  request: RunRequest,
+  error: ErrorEnvelope,
+  metadata: Partial<RunResponse["metadata"]>,
+  startTime: number
+): RunResponse {
+  const completedAt = new Date().toISOString();
+  return {
+    requestId: request.requestId,
+    traceId: request.traceId,
+    ok: false,
+    error,
+    metadata: {
+      startedAt: metadata.startedAt || completedAt,
+      completedAt,
+      durationMs: Date.now() - startTime,
+      tool: metadata.tool || request.tool,
+      cliCommand: metadata.cliCommand,
+      exitCode: metadata.exitCode,
+    },
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REGISTRY UTILITIES (exported for testing)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export function getAllTools(): ToolDefinition[] {
+  const registry = loadRegistry();
+  return Object.values(registry.tools);
+}
+
+export function getToolByName(name: string): ToolDefinition | null {
+  return getToolDefinition(name);
+}
+
+export function listToolNames(): string[] {
+  const registry = loadRegistry();
+  return Object.keys(registry.tools);
+}
+
+export function getToolsByTier(tier: "free" | "pro"): ToolDefinition[] {
+  return getAllTools().filter((t) => t.tier === tier);
+}
+
+export function getToolsByCategory(category: string): ToolDefinition[] {
+  return getAllTools().filter((t) => t.category === category);
+}
+
+/**
+ * Validate the entire registry
+ */
+export function validateRegistry(): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const registry = loadRegistry();
+
+  for (const [name, tool] of Object.entries(registry.tools)) {
+    // Check name matches key
+    if (tool.name !== name) {
+      errors.push(`Tool '${name}' has mismatched name property: '${tool.name}'`);
+    }
+
+    // Check required fields
+    if (!tool.tier) errors.push(`Tool '${name}' missing tier`);
+    if (!tool.category) errors.push(`Tool '${name}' missing category`);
+    if (!tool.inputSchema) errors.push(`Tool '${name}' missing inputSchema`);
+    if (!tool.outputSchema) errors.push(`Tool '${name}' missing outputSchema`);
+    if (!tool.cli) errors.push(`Tool '${name}' missing cli mapping`);
+    if (!tool.cli?.command) errors.push(`Tool '${name}' missing cli.command`);
+    if (!tool.cli?.argMap) errors.push(`Tool '${name}' missing cli.argMap`);
+
+    // Validate tier
+    if (tool.tier && !["free", "pro"].includes(tool.tier)) {
+      errors.push(`Tool '${name}' has invalid tier: '${tool.tier}'`);
+    }
+
+    // Validate input schema is valid JSON Schema
+    if (tool.inputSchema) {
+      try {
+        ajv.compile(tool.inputSchema);
+      } catch (err) {
+        errors.push(`Tool '${name}' has invalid inputSchema: ${(err as Error).message}`);
+      }
+    }
+
+    // Validate output schema is valid JSON Schema
+    if (tool.outputSchema) {
+      try {
+        ajv.compile(tool.outputSchema);
+      } catch (err) {
+        errors.push(`Tool '${name}' has invalid outputSchema: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEFAULT EXPORT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export default {
+  handleToolRequest,
+  getAllTools,
+  getToolByName,
+  listToolNames,
+  getToolsByTier,
+  getToolsByCategory,
+  validateRegistry,
+};