@vibecheckai/cli 3.5.0 → 3.5.1

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

@@ -0,0 +1,671 @@
+/**
+ * Unified Tool Handler
+ * 
+ * Single entry point for all MCP tool calls.
+ * Handles:
+ * - Schema validation
+ * - Tier checking
+ * - Execution routing
+ * - Response normalization
+ * - Error handling
+ * 
+ * CRITICAL: Deterministic output. Stable IDs. Stable sorting.
+ * Agents must not thrash.
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+import { validateToolInput, validateProjectPath } from '../lib/validator.js';
+import { createErrorEnvelope, createSuccessEnvelope, Errors, ErrorCode } from '../lib/errors.js';
+import { createSandbox } from '../lib/sandbox.js';
+import { getGlobalCache } from '../lib/cache.js';
+import { createRequestLogger } from '../lib/logger.js';
+import { ToolExecutors, cancelExecution } from '../lib/executor.js';
+import { checkFeatureAccess, TIERS } from '../tier-auth.js';
+import { generateRequestId, generateFindingId, sortFindings } from '../lib/ids.js';
+import { getMetricsCollector, recordFindings } from '../lib/metrics.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Load tool registry
+ */
+function loadRegistry() {
+  const registryPath = join(__dirname, '..', 'registry', 'tools.json');
+  return JSON.parse(readFileSync(registryPath, 'utf-8'));
+}
+
+/**
+ * Tool request
+ */
+export interface ToolRequest {
+  tool: string;
+  projectPath: string;
+  requestId?: string;
+  timeout?: number;
+  cache?: {
+    mode?: 'auto' | 'force' | 'skip';
+    maxAge?: number;
+  };
+  options?: Record<string, unknown>;
+  apiKey?: string;
+}
+
+/**
+ * Tool response (success or error)
+ */
+export type ToolResponse = 
+  | { ok: true; data: unknown; meta?: { cached?: boolean; durationMs?: number; requestId?: string }; timestamp: string }
+  | { ok: false; error: { code: string; message: string; retryable?: boolean; userAction?: string }; requestId: string; timestamp: string };
+
+/**
+ * Main tool handler
+ */
+export async function handleTool(request: ToolRequest): Promise<ToolResponse> {
+  const startTime = Date.now();
+  const requestId = request.requestId ?? generateRequestId();
+  const logger = createRequestLogger(requestId);
+  const metrics = getMetricsCollector();
+  
+  logger.info('Tool request received', { tool: request.tool, projectPath: request.projectPath });
+
+  try {
+    // 1. Load registry and find tool
+    const registry = loadRegistry();
+    const toolDef = registry.tools.find((t: { name: string }) => t.name === request.tool);
+    
+    // Check aliases
+    if (!toolDef && registry.aliases[request.tool]) {
+      const aliasTarget = registry.aliases[request.tool];
+      logger.warn('Using deprecated alias', { alias: request.tool, target: aliasTarget });
+      request.tool = aliasTarget;
+    }
+
+    // Check deprecated
+    const deprecated = registry.deprecated?.find((d: { name: string }) => 
+      d.name === request.tool || request.tool.match(new RegExp(d.name.replace('*', '.*')))
+    );
+    if (deprecated) {
+      logger.warn('Deprecated tool called', { 
+        tool: request.tool, 
+        replacement: deprecated.replacement,
+        removeIn: deprecated.removeIn 
+      });
+    }
+
+    // Tool not found
+    if (!toolDef && !registry.aliases[request.tool]) {
+      return createErrorEnvelope(
+        Errors.invalidInput(`Unknown tool: ${request.tool}. Available tools: ${registry.tools.map((t: { name: string }) => t.name).join(', ')}`),
+        requestId
+      ) as ToolResponse;
+    }
+
+    const tool = toolDef ?? registry.tools.find((t: { name: string }) => t.name === registry.aliases[request.tool]);
+
+    // 2. Validate input schema
+    const validation = validateToolInput(tool.name, request.options ?? {});
+    if (!validation.valid) {
+      return createErrorEnvelope(
+        Errors.invalidInput(`Invalid input: ${validation.errors?.map(e => `${e.path}: ${e.message}`).join(', ')}`),
+        requestId
+      ) as ToolResponse;
+    }
+
+    // 3. Validate project path
+    const pathValidation = validateProjectPath(request.projectPath);
+    if (!pathValidation.valid) {
+      return createErrorEnvelope(
+        Errors.pathOutsideSandbox(request.projectPath, process.cwd()),
+        requestId
+      ) as ToolResponse;
+    }
+
+    // 4. Check tier access
+    const tierAccess = await checkFeatureAccess(tool.tier, request.apiKey);
+    if (!tierAccess.hasAccess) {
+      return createErrorEnvelope(
+        Errors.tierRequired(tool.name, tool.tier, tierAccess.tier),
+        requestId
+      ) as ToolResponse;
+    }
+
+    // Check tier-gated options
+    if (tool.tierGated) {
+      for (const [option, requiredTier] of Object.entries(tool.tierGated)) {
+        if (request.options?.[option]) {
+          const optionAccess = await checkFeatureAccess(requiredTier as string, request.apiKey);
+          if (!optionAccess.hasAccess) {
+            return createErrorEnvelope(
+              Errors.tierRequired(`${tool.name} --${option}`, requiredTier as string, optionAccess.tier),
+              requestId
+            ) as ToolResponse;
+          }
+        }
+      }
+    }
+
+    // 5. Check cache
+    const cache = getGlobalCache();
+    const cacheMode = request.cache?.mode ?? 'auto';
+    
+    if (tool.cacheable && cacheMode !== 'skip') {
+      const cacheKey = cache.generateKey(tool.name, request.projectPath, request.options);
+      const cached = cache.get(cacheKey);
+      
+      if (cached.cached) {
+        const cacheMaxAge = request.cache?.maxAge ?? tool.cacheMaxAge ?? 300;
+        if (cached.age < cacheMaxAge * 1000) {
+          logger.info('Cache hit', { tool: tool.name, cacheAge: cached.age });
+          return createSuccessEnvelope(cached.data, {
+            cached: true,
+            cacheAge: cached.age,
+            durationMs: Date.now() - startTime,
+            requestId,
+          }) as ToolResponse;
+        }
+      }
+    }
+
+    // 6. Execute tool
+    logger.info('Executing tool', { tool: tool.name, cli: tool.cli });
+    
+    const result = await executeToolByName(tool.name, request.projectPath, request.options ?? {}, {
+      timeout: request.timeout ?? tool.timeout ?? 120000,
+      requestId,
+    });
+
+    // 7. Cache result if successful
+    if (result.ok && tool.cacheable && cacheMode !== 'skip') {
+      const cacheKey = cache.generateKey(tool.name, request.projectPath, request.options);
+      cache.set(cacheKey, result.data, { ttl: tool.cacheMaxAge ?? 300 });
+    }
+
+    // 8. Post-process result for determinism
+    const durationMs = Date.now() - startTime;
+    logger.info('Tool completed', { tool: tool.name, durationMs, ok: result.ok });
+
+    if (result.ok) {
+      // Normalize findings with deterministic IDs and sorting
+      const normalizedData = normalizeOutput(result.data, tool.name);
+      
+      // Record metrics
+      const findings = (normalizedData as { findings?: unknown[] })?.findings ?? [];
+      if (findings.length > 0) {
+        recordFindings(tool.name, findings as { severity?: string }[]);
+      }
+      metrics.recordToolExecution(tool.name, durationMs, true, false);
+      
+      return createSuccessEnvelope(normalizedData, {
+        cached: false,
+        durationMs,
+        requestId,
+      }) as ToolResponse;
+    } else {
+      metrics.recordToolExecution(tool.name, durationMs, false, false);
+      return createErrorEnvelope(
+        Errors.cliError(result.error?.message ?? 'Unknown error', result.exitCode),
+        requestId
+      ) as ToolResponse;
+    }
+
+  } catch (error) {
+    const durationMs = Date.now() - startTime;
+    logger.error('Tool error', error instanceof Error ? error : new Error(String(error)));
+    
+    return createErrorEnvelope(error, requestId) as ToolResponse;
+  }
+}
+
+/**
+ * Normalize output for determinism
+ * 
+ * - Add stable IDs to findings
+ * - Sort findings deterministically
+ * - Ensure consistent field ordering
+ */
+function normalizeOutput(data: unknown, toolName: string): unknown {
+  if (!data || typeof data !== 'object') {
+    return data;
+  }
+
+  const obj = data as Record<string, unknown>;
+  
+  // Process findings array if present
+  if (Array.isArray(obj.findings)) {
+    obj.findings = normalizeFindings(obj.findings);
+  }
+  
+  // Process blockers array if present
+  if (Array.isArray(obj.blockers)) {
+    obj.blockers = normalizeFindings(obj.blockers);
+  }
+  
+  // Process topIssues array if present
+  if (Array.isArray(obj.topIssues)) {
+    obj.topIssues = normalizeFindings(obj.topIssues);
+  }
+
+  return obj;
+}
+
+/**
+ * Normalize findings with stable IDs and sorting
+ */
+function normalizeFindings(findings: unknown[]): unknown[] {
+  const normalized = findings.map((finding, index) => {
+    if (!finding || typeof finding !== 'object') {
+      return finding;
+    }
+    
+    const f = finding as Record<string, unknown>;
+    
+    // Generate stable ID if missing or invalid
+    if (!f.id || typeof f.id !== 'string' || !f.id.match(/^[a-z_]+-[a-f0-9]{8}$/)) {
+      const category = (f.category as string) || (f.rule_id as string)?.split('.')[0] || 'unknown';
+      const evidence = Array.isArray(f.evidence) ? f.evidence[0] : {};
+      const evidenceObj = evidence as { file?: string; line?: number };
+      
+      f.id = generateFindingId(
+        category,
+        {
+          path: evidenceObj?.file || `finding-${index}`,
+          lineStart: evidenceObj?.line || 0,
+          message: (f.title as string) || (f.message as string) || '',
+        }
+      );
+    }
+    
+    return f;
+  });
+  
+  // Sort deterministically
+  return sortFindings(normalized as Array<{ 
+    severity?: string; 
+    rule_id?: string; 
+    ruleId?: string; 
+    evidence?: Array<{ file?: string; line?: number }>; 
+    title?: string;
+  }>);
+}
+
+/**
+ * Execute tool by name
+ */
+async function executeToolByName(
+  toolName: string,
+  projectPath: string,
+  options: Record<string, unknown>,
+  execOptions: { timeout: number; requestId: string }
+): Promise<{ ok: boolean; data?: unknown; error?: { message: string }; exitCode?: number }> {
+  const baseOptions = {
+    projectPath,
+    timeout: execOptions.timeout,
+    requestId: execOptions.requestId,
+  };
+
+  switch (toolName) {
+    case 'vibecheck.doctor':
+      return ToolExecutors.doctor(baseOptions);
+
+    case 'vibecheck.init':
+      return ToolExecutors.init({ ...baseOptions, force: options.force as boolean });
+
+    case 'vibecheck.scan':
+      return ToolExecutors.scan({
+        ...baseOptions,
+        profile: options.profile as string,
+        since: options.since as string,
+      });
+
+    case 'vibecheck.ship':
+      return ToolExecutors.ship({
+        ...baseOptions,
+        strict: options.strict as boolean,
+        mockproof: options.mockproof as boolean,
+      });
+
+    case 'vibecheck.prove':
+      return ToolExecutors.prove({
+        ...baseOptions,
+        url: options.url as string,
+        auth: options.auth as string,
+        maxFixRounds: options.maxFixRounds as number,
+        skipReality: options.skipReality as boolean,
+      });
+
+    case 'vibecheck.reality':
+      return ToolExecutors.reality({
+        ...baseOptions,
+        url: options.url as string,
+        auth: options.auth as string,
+        verifyAuth: options.verifyAuth as boolean,
+        maxPages: options.maxPages as number,
+      });
+
+    case 'vibecheck.fix':
+      return ToolExecutors.fix({
+        ...baseOptions,
+        apply: options.apply as boolean,
+        promptOnly: options.promptOnly as boolean,
+        autopilot: options.autopilot as boolean,
+        maxMissions: options.maxMissions as number,
+      });
+
+    case 'vibecheck.guard':
+      return ToolExecutors.guard({
+        ...baseOptions,
+        claims: options.claims as boolean,
+        hallucinations: options.hallucinations as boolean,
+        prompts: options.prompts as boolean,
+      });
+
+    case 'vibecheck.ctx':
+      return ToolExecutors.ctx({
+        ...baseOptions,
+        snapshot: options.snapshot as boolean,
+      });
+
+    case 'vibecheck.report':
+      return ToolExecutors.report({
+        ...baseOptions,
+        type: options.type as string,
+        format: options.format as string,
+        output: options.output as string,
+      });
+
+    case 'vibecheck.polish':
+      return ToolExecutors.polish({
+        ...baseOptions,
+        category: options.category as string,
+        fix: options.fix as boolean,
+      });
+
+    case 'vibecheck.status':
+      return ToolExecutors.status(baseOptions);
+
+    case 'vibecheck.share':
+      return ToolExecutors.share({
+        ...baseOptions,
+        missionDir: options.missionDir as string,
+      });
+
+    case 'vibecheck.badge':
+      return ToolExecutors.badge({
+        ...baseOptions,
+        format: options.format as string,
+        style: options.style as string,
+      });
+
+    // Query tools (non-CLI)
+    case 'vibecheck.get_truthpack':
+      return handleGetTruthpack(projectPath, options);
+
+    case 'vibecheck.validate_claim':
+      return handleValidateClaim(projectPath, options);
+
+    case 'vibecheck.search_evidence':
+      return handleSearchEvidence(projectPath, options);
+
+    case 'vibecheck.list_reports':
+      return handleListReports(projectPath, options);
+
+    case 'vibecheck.get_last_verdict':
+      return handleGetLastVerdict(projectPath);
+
+    case 'vibecheck.get_finding':
+      return handleGetFinding(projectPath, options);
+
+    default:
+      return { ok: false, error: { message: `No executor for tool: ${toolName}` } };
+  }
+}
+
+/**
+ * Query tool handlers
+ */
+import { readFileSync as readSync, existsSync, readdirSync, statSync } from 'fs';
+
+async function handleGetTruthpack(projectPath: string, options: Record<string, unknown>) {
+  const truthpackPaths = [
+    join(projectPath, '.vibecheck', 'truthpack.json'),
+    join(projectPath, '.vibecheck', 'truth', 'truthpack.json'),
+  ];
+
+  for (const path of truthpackPaths) {
+    if (existsSync(path)) {
+      try {
+        const data = JSON.parse(readSync(path, 'utf-8'));
+        return { ok: true, data };
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  // If refresh requested or not found, run ctx
+  if (options.refresh) {
+    return ToolExecutors.ctx({ projectPath, timeout: 90000 });
+  }
+
+  return { ok: false, error: { message: 'Truthpack not found. Run vibecheck.ctx first.' } };
+}
+
+async function handleValidateClaim(projectPath: string, options: Record<string, unknown>) {
+  const claim = options.claim as string;
+  const type = options.type as string;
+
+  // Load truthpack
+  const truthpackResult = await handleGetTruthpack(projectPath, {});
+  if (!truthpackResult.ok) {
+    return { ok: false, error: { message: 'Cannot validate claim: truthpack not available' } };
+  }
+
+  const truthpack = truthpackResult.data as Record<string, unknown>;
+
+  // Simple validation logic
+  if (type === 'route_exists') {
+    const routes = (truthpack.routes as { server?: Array<{ path: string }> })?.server ?? [];
+    const found = routes.some(r => r.path === claim || r.path.includes(claim));
+    return {
+      ok: true,
+      data: {
+        valid: found,
+        claim,
+        type,
+        evidence: found ? routes.filter(r => r.path.includes(claim)).slice(0, 3) : [],
+      },
+    };
+  }
+
+  if (type === 'env_var_used') {
+    const vars = (truthpack.env as { vars?: Array<{ name: string }> })?.vars ?? [];
+    const found = vars.some(v => v.name === claim);
+    return {
+      ok: true,
+      data: {
+        valid: found,
+        claim,
+        type,
+        evidence: found ? vars.filter(v => v.name === claim) : [],
+      },
+    };
+  }
+
+  if (type === 'file_exists') {
+    const exists = existsSync(join(projectPath, claim));
+    return {
+      ok: true,
+      data: {
+        valid: exists,
+        claim,
+        type,
+        evidence: exists ? [{ file: claim }] : [],
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    data: {
+      valid: 'unknown',
+      claim,
+      type,
+      reason: 'Claim type not supported',
+    },
+  };
+}
+
+async function handleSearchEvidence(projectPath: string, options: Record<string, unknown>) {
+  const query = options.query as string;
+  const type = options.type as string ?? 'any';
+  const limit = options.limit as number ?? 10;
+
+  // Load truthpack
+  const truthpackResult = await handleGetTruthpack(projectPath, {});
+  if (!truthpackResult.ok) {
+    return { ok: false, error: { message: 'Cannot search: truthpack not available' } };
+  }
+
+  const truthpack = truthpackResult.data as Record<string, unknown>;
+  const results: Array<{ type: string; match: unknown; confidence: number }> = [];
+
+  // Search routes
+  if (type === 'any' || type === 'route') {
+    const routes = (truthpack.routes as { server?: Array<{ path: string; file?: string }> })?.server ?? [];
+    for (const route of routes) {
+      if (route.path.includes(query)) {
+        results.push({ type: 'route', match: route, confidence: 0.9 });
+      }
+    }
+  }
+
+  // Search env vars
+  if (type === 'any' || type === 'env_var') {
+    const vars = (truthpack.env as { vars?: Array<{ name: string }> })?.vars ?? [];
+    for (const v of vars) {
+      if (v.name.includes(query)) {
+        results.push({ type: 'env_var', match: v, confidence: 0.95 });
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    data: {
+      query,
+      type,
+      results: results.slice(0, limit),
+      total: results.length,
+    },
+  };
+}
+
+async function handleListReports(projectPath: string, options: Record<string, unknown>) {
+  const vibecheckDir = join(projectPath, '.vibecheck');
+  if (!existsSync(vibecheckDir)) {
+    return { ok: true, data: { reports: [] } };
+  }
+
+  const reports: Array<{ type: string; path: string; created: number }> = [];
+
+  // Check common report locations
+  const reportFiles = [
+    { type: 'verdict', path: 'last_ship.json' },
+    { type: 'truthpack', path: 'truthpack.json' },
+    { type: 'truthpack', path: 'truth/truthpack.json' },
+    { type: 'summary', path: 'summary.json' },
+    { type: 'sarif', path: 'results.sarif' },
+    { type: 'html', path: 'report.html' },
+  ];
+
+  for (const { type, path } of reportFiles) {
+    const fullPath = join(vibecheckDir, path);
+    if (existsSync(fullPath)) {
+      const stat = statSync(fullPath);
+      reports.push({ type, path: `.vibecheck/${path}`, created: stat.mtimeMs });
+    }
+  }
+
+  // Check missions directory
+  const missionsDir = join(vibecheckDir, 'missions');
+  if (existsSync(missionsDir)) {
+    const dirs = readdirSync(missionsDir).filter(d => /^\d+$/.test(d));
+    for (const dir of dirs.slice(-5)) {
+      reports.push({
+        type: 'mission',
+        path: `.vibecheck/missions/${dir}`,
+        created: parseInt(dir, 10),
+      });
+    }
+  }
+
+  return {
+    ok: true,
+    data: {
+      reports: reports.sort((a, b) => b.created - a.created).slice(0, options.limit as number ?? 10),
+    },
+  };
+}
+
+async function handleGetLastVerdict(projectPath: string) {
+  const verdictPath = join(projectPath, '.vibecheck', 'last_ship.json');
+  
+  if (!existsSync(verdictPath)) {
+    return { ok: false, error: { message: 'No verdict found. Run vibecheck.ship first.' } };
+  }
+
+  try {
+    const data = JSON.parse(readSync(verdictPath, 'utf-8'));
+    return { ok: true, data };
+  } catch {
+    return { ok: false, error: { message: 'Failed to read verdict file' } };
+  }
+}
+
+async function handleGetFinding(projectPath: string, options: Record<string, unknown>) {
+  const findingId = options.findingId as string;
+  
+  // Load last ship report
+  const verdictResult = await handleGetLastVerdict(projectPath);
+  if (!verdictResult.ok) {
+    return verdictResult;
+  }
+
+  const verdict = verdictResult.data as { findings?: Array<{ id: string }> };
+  const finding = verdict.findings?.find(f => f.id === findingId);
+
+  if (!finding) {
+    return { ok: false, error: { message: `Finding not found: ${findingId}` } };
+  }
+
+  return { ok: true, data: finding };
+}
+
+/**
+ * Cancel a running tool execution
+ */
+export function cancelTool(requestId: string): boolean {
+  return cancelExecution(requestId);
+}
+
+/**
+ * List available tools
+ */
+export function listTools(): Array<{ name: string; description: string; tier: string; category: string }> {
+  const registry = loadRegistry();
+  return registry.tools.map((t: { name: string; description: string; tier: string; category: string }) => ({
+    name: t.name,
+    description: t.description,
+    tier: t.tier,
+    category: t.category,
+  }));
+}
+
+export default {
+  handleTool,
+  cancelTool,
+  listTools,
+};