@vibecheckai/cli 3.5.1 → 3.5.2

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

@@ -1,671 +1,554 @@
 /**
- * Unified Tool Handler
+ * Universal Tool Handler
  * 
- * Single entry point for all MCP tool calls.
- * Handles:
- * - Schema validation
- * - Tier checking
- * - Execution routing
- * - Response normalization
- * - Error handling
+ * Registry-driven dispatcher for all MCP tools.
  * 
- * CRITICAL: Deterministic output. Stable IDs. Stable sorting.
- * Agents must not thrash.
+ * 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 { 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';
+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>;
+}
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+let registryCache: ToolRegistry | null = null;
 
 /**
- * Load tool registry
+ * Load tool registry (cached)
  */
-function loadRegistry() {
-  const registryPath = join(__dirname, '..', 'registry', 'tools.json');
-  return JSON.parse(readFileSync(registryPath, 'utf-8'));
+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;
 }
 
 /**
- * Tool request
+ * Get tool definition by name (supports aliases)
  */
-export interface ToolRequest {
-  tool: string;
-  projectPath: string;
-  requestId?: string;
-  timeout?: number;
-  cache?: {
-    mode?: 'auto' | 'force' | 'skip';
-    maxAge?: number;
-  };
-  options?: Record<string, unknown>;
-  apiKey?: string;
+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 });
+
 /**
- * Tool response (success or error)
+ * Validate data against JSON schema
  */
-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 };
+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
+// ═══════════════════════════════════════════════════════════════════════════════
 
 /**
- * Main tool handler
+ * Handle a tool execution request
  */
-export async function handleTool(request: ToolRequest): Promise<ToolResponse> {
+export async function handleToolRequest(request: RunRequest): Promise<RunResponse> {
+  const startedAt = new Date().toISOString();
   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 
-      });
-    }
+  const baseMetadata = {
+    startedAt,
+    completedAt: "",
+    durationMs: 0,
+    tool: request.tool,
+  };
 
-    // 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;
+  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
+      );
     }
 
-    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;
+    // 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 project path
-    const pathValidation = validateProjectPath(request.projectPath);
-    if (!pathValidation.valid) {
-      return createErrorEnvelope(
-        Errors.pathOutsideSandbox(request.projectPath, process.cwd()),
-        requestId
-      ) as ToolResponse;
+    // 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. 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;
+    // 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
+      );
     }
 
-    // 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;
-          }
+    // 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. 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;
-        }
-      }
-    }
+    // 5) Build CLI arguments
+    const cliArgs = buildCliArgs(
+      { ...request.args, projectPath: resolvedProjectPath },
+      toolDef.cli.argMap,
+      toolDef.cli.fixedFlags
+    );
 
-    // 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,
+    // 6) Execute CLI command
+    const executor = new CliExecutor({
+      cwd: resolvedProjectPath,
+      timeoutMs: toolDef.cli.timeoutMs || 300000,
+      requestId: request.requestId,
+      traceId: request.traceId,
     });
 
-    // 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 });
+    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
+      );
     }
 
-    // 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;
+    // 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
+      );
     }
 
-  } 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,
+    // 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
+        ),
         {
-          path: evidenceObj?.file || `finding-${index}`,
-          lineStart: evidenceObj?.line || 0,
-          message: (f.title as string) || (f.message as string) || '',
-        }
+          ...baseMetadata,
+          cliCommand: `vibecheck ${toolDef.cli.command}`,
+          exitCode: execResult.exitCode,
+        },
+        startTime
       );
     }
-    
-    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;
-      }
+    // 8) Sort findings for stable output
+    if (toolResult.findings) {
+      toolResult.findings = sortFindings(toolResult.findings);
     }
-  }
 
-  // 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) : [],
-      },
-    };
-  }
+    // 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)
+      );
+    }
 
-  if (type === 'file_exists') {
-    const exists = existsSync(join(projectPath, claim));
+    // 10) Build success response
+    const completedAt = new Date().toISOString();
     return {
+      requestId: request.requestId,
+      traceId: request.traceId,
       ok: true,
-      data: {
-        valid: exists,
-        claim,
-        type,
-        evidence: exists ? [{ file: claim }] : [],
+      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 {
-    ok: true,
-    data: {
-      valid: 'unknown',
-      claim,
-      type,
-      reason: 'Claim type not supported',
+    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,
     },
   };
 }
 
-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;
+// ═══════════════════════════════════════════════════════════════════════════════
+// REGISTRY UTILITIES (exported for testing)
+// ═══════════════════════════════════════════════════════════════════════════════
 
-  // Load truthpack
-  const truthpackResult = await handleGetTruthpack(projectPath, {});
-  if (!truthpackResult.ok) {
-    return { ok: false, error: { message: 'Cannot search: truthpack not available' } };
-  }
+export function getAllTools(): ToolDefinition[] {
+  const registry = loadRegistry();
+  return Object.values(registry.tools);
+}
 
-  const truthpack = truthpackResult.data as Record<string, unknown>;
-  const results: Array<{ type: string; match: unknown; confidence: number }> = [];
+export function getToolByName(name: string): ToolDefinition | null {
+  return getToolDefinition(name);
+}
 
-  // 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 });
-      }
-    }
-  }
+export function listToolNames(): string[] {
+  const registry = loadRegistry();
+  return Object.keys(registry.tools);
+}
 
-  // 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 });
-      }
-    }
-  }
+export function getToolsByTier(tier: "free" | "pro"): ToolDefinition[] {
+  return getAllTools().filter((t) => t.tier === tier);
+}
 
-  return {
-    ok: true,
-    data: {
-      query,
-      type,
-      results: results.slice(0, limit),
-      total: results.length,
-    },
-  };
+export function getToolsByCategory(category: string): ToolDefinition[] {
+  return getAllTools().filter((t) => t.category === category);
 }
 
-async function handleListReports(projectPath: string, options: Record<string, unknown>) {
-  const vibecheckDir = join(projectPath, '.vibecheck');
-  if (!existsSync(vibecheckDir)) {
-    return { ok: true, data: { reports: [] } };
-  }
+/**
+ * Validate the entire registry
+ */
+export function validateRegistry(): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const registry = loadRegistry();
 
-  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 });
+  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 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),
-      });
+    // 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}'`);
     }
-  }
 
-  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);
+    // 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}`);
+      }
+    }
 
-  if (!finding) {
-    return { ok: false, error: { message: `Finding not found: ${findingId}` } };
+    // 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 { ok: true, data: finding };
-}
-
-/**
- * Cancel a running tool execution
- */
-export function cancelTool(requestId: string): boolean {
-  return cancelExecution(requestId);
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
 }
 
-/**
- * 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,
-  }));
-}
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEFAULT EXPORT
+// ═══════════════════════════════════════════════════════════════════════════════
 
 export default {
-  handleTool,
-  cancelTool,
-  listTools,
+  handleToolRequest,
+  getAllTools,
+  getToolByName,
+  listToolNames,
+  getToolsByTier,
+  getToolsByCategory,
+  validateRegistry,
 };