@vibecheckai/cli 3.4.0 → 3.5.1

package/mcp-server/lib/cache.ts

@@ -0,0 +1,341 @@
+/**
+ * Caching Layer for MCP Server
+ * 
+ * Provides deterministic caching with:
+ * - Project fingerprinting for cache invalidation
+ * - Incremental run detection
+ * - TTL-based expiration
+ * - Memory + disk caching
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+/**
+ * Cache entry structure
+ */
+export interface CacheEntry<T> {
+  data: T;
+  fingerprint: string;
+  timestamp: number;
+  ttl: number;
+  hits: number;
+}
+
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+  maxMemoryEntries?: number;
+  defaultTtl?: number;
+  diskCacheDir?: string;
+}
+
+/**
+ * Project fingerprint - used for cache invalidation
+ */
+export interface ProjectFingerprint {
+  hash: string;
+  fileCount: number;
+  lastModified: number;
+  packageJsonHash?: string;
+  lockfileHash?: string;
+}
+
+/**
+ * In-memory LRU cache
+ */
+class MemoryCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private maxEntries: number;
+
+  constructor(maxEntries = 100) {
+    this.maxEntries = maxEntries;
+  }
+
+  get(key: string): CacheEntry<T> | undefined {
+    const entry = this.cache.get(key);
+    if (entry) {
+      // Move to end (most recently used)
+      this.cache.delete(key);
+      entry.hits++;
+      this.cache.set(key, entry);
+    }
+    return entry;
+  }
+
+  set(key: string, entry: CacheEntry<T>): void {
+    // Evict oldest if at capacity
+    if (this.cache.size >= this.maxEntries) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) this.cache.delete(firstKey);
+    }
+    this.cache.set(key, entry);
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Main cache class
+ */
+export class VibecheckCache {
+  private memoryCache: MemoryCache<unknown>;
+  private diskCacheDir?: string;
+  private defaultTtl: number;
+  private fingerprintCache = new Map<string, ProjectFingerprint>();
+
+  constructor(config: CacheConfig = {}) {
+    this.memoryCache = new MemoryCache(config.maxMemoryEntries ?? 100);
+    this.diskCacheDir = config.diskCacheDir;
+    this.defaultTtl = config.defaultTtl ?? 300; // 5 minutes
+
+    // Create disk cache dir if specified
+    if (this.diskCacheDir && !existsSync(this.diskCacheDir)) {
+      mkdirSync(this.diskCacheDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Generate cache key
+   */
+  generateKey(tool: string, projectPath: string, options?: Record<string, unknown>): string {
+    const fingerprint = this.getProjectFingerprint(projectPath);
+    const optionsHash = options ? createHash('md5').update(JSON.stringify(options)).digest('hex').substring(0, 8) : '';
+    return `${tool}:${fingerprint.hash}:${optionsHash}`;
+  }
+
+  /**
+   * Get from cache
+   */
+  get<T>(key: string): { data: T; cached: true; age: number } | { cached: false } {
+    // Try memory cache first
+    const memEntry = this.memoryCache.get(key) as CacheEntry<T> | undefined;
+    if (memEntry) {
+      const age = Date.now() - memEntry.timestamp;
+      if (age < memEntry.ttl * 1000) {
+        return { data: memEntry.data, cached: true, age };
+      }
+      // Expired - remove
+      this.memoryCache.delete(key);
+    }
+
+    // Try disk cache
+    if (this.diskCacheDir) {
+      const diskEntry = this.getDiskCache<T>(key);
+      if (diskEntry) {
+        const age = Date.now() - diskEntry.timestamp;
+        if (age < diskEntry.ttl * 1000) {
+          // Promote to memory cache
+          this.memoryCache.set(key, diskEntry);
+          return { data: diskEntry.data, cached: true, age };
+        }
+      }
+    }
+
+    return { cached: false };
+  }
+
+  /**
+   * Set cache entry
+   */
+  set<T>(
+    key: string,
+    data: T,
+    options?: { ttl?: number; fingerprint?: string }
+  ): void {
+    const entry: CacheEntry<T> = {
+      data,
+      fingerprint: options?.fingerprint ?? '',
+      timestamp: Date.now(),
+      ttl: options?.ttl ?? this.defaultTtl,
+      hits: 0,
+    };
+
+    // Set in memory cache
+    this.memoryCache.set(key, entry as CacheEntry<unknown>);
+
+    // Persist to disk if configured
+    if (this.diskCacheDir) {
+      this.setDiskCache(key, entry);
+    }
+  }
+
+  /**
+   * Invalidate cache for a project
+   */
+  invalidate(projectPath: string): void {
+    // Clear fingerprint cache
+    this.fingerprintCache.delete(projectPath);
+    
+    // We can't easily clear memory cache by project, so we rely on fingerprint mismatches
+  }
+
+  /**
+   * Get project fingerprint for cache invalidation
+   */
+  getProjectFingerprint(projectPath: string): ProjectFingerprint {
+    // Check cache first
+    const cached = this.fingerprintCache.get(projectPath);
+    if (cached) {
+      return cached;
+    }
+
+    const fingerprint = this.computeProjectFingerprint(projectPath);
+    this.fingerprintCache.set(projectPath, fingerprint);
+    return fingerprint;
+  }
+
+  /**
+   * Compute project fingerprint
+   */
+  private computeProjectFingerprint(projectPath: string): ProjectFingerprint {
+    const hash = createHash('md5');
+    let fileCount = 0;
+    let lastModified = 0;
+
+    // Hash key files that indicate project changes
+    const keyFiles = [
+      'package.json',
+      'package-lock.json',
+      'pnpm-lock.yaml',
+      'yarn.lock',
+      'tsconfig.json',
+      '.vibecheckrc',
+      'vibecheck.config.json',
+    ];
+
+    let packageJsonHash: string | undefined;
+    let lockfileHash: string | undefined;
+
+    for (const file of keyFiles) {
+      const filePath = join(projectPath, file);
+      if (existsSync(filePath)) {
+        try {
+          const stat = statSync(filePath);
+          const content = readFileSync(filePath);
+          hash.update(content);
+          lastModified = Math.max(lastModified, stat.mtimeMs);
+          fileCount++;
+
+          if (file === 'package.json') {
+            packageJsonHash = createHash('md5').update(content).digest('hex').substring(0, 8);
+          }
+          if (file.includes('lock')) {
+            lockfileHash = createHash('md5').update(content).digest('hex').substring(0, 8);
+          }
+        } catch {
+          // Skip inaccessible files
+        }
+      }
+    }
+
+    // Also check .vibecheck directory
+    const vibecheckDir = join(projectPath, '.vibecheck');
+    if (existsSync(vibecheckDir)) {
+      try {
+        const stat = statSync(vibecheckDir);
+        lastModified = Math.max(lastModified, stat.mtimeMs);
+      } catch {
+        // Skip
+      }
+    }
+
+    return {
+      hash: hash.digest('hex').substring(0, 16),
+      fileCount,
+      lastModified,
+      packageJsonHash,
+      lockfileHash,
+    };
+  }
+
+  /**
+   * Disk cache operations
+   */
+  private getDiskCache<T>(key: string): CacheEntry<T> | null {
+    if (!this.diskCacheDir) return null;
+
+    const filePath = join(this.diskCacheDir, `${this.sanitizeKey(key)}.json`);
+    if (!existsSync(filePath)) return null;
+
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      return JSON.parse(content) as CacheEntry<T>;
+    } catch {
+      return null;
+    }
+  }
+
+  private setDiskCache<T>(key: string, entry: CacheEntry<T>): void {
+    if (!this.diskCacheDir) return;
+
+    const filePath = join(this.diskCacheDir, `${this.sanitizeKey(key)}.json`);
+    try {
+      writeFileSync(filePath, JSON.stringify(entry), 'utf-8');
+    } catch {
+      // Ignore disk write errors
+    }
+  }
+
+  private sanitizeKey(key: string): string {
+    return key.replace(/[^a-zA-Z0-9_-]/g, '_').substring(0, 100);
+  }
+
+  /**
+   * Check if an incremental run is possible
+   */
+  canRunIncremental(projectPath: string, lastRunFingerprint: string): boolean {
+    const currentFingerprint = this.getProjectFingerprint(projectPath);
+    return currentFingerprint.hash !== lastRunFingerprint;
+  }
+
+  /**
+   * Clear all caches
+   */
+  clear(): void {
+    this.memoryCache.clear();
+    this.fingerprintCache.clear();
+  }
+
+  /**
+   * Get cache stats
+   */
+  getStats(): { memoryEntries: number; fingerprintEntries: number } {
+    return {
+      memoryEntries: this.memoryCache.size(),
+      fingerprintEntries: this.fingerprintCache.size,
+    };
+  }
+}
+
+// Singleton instance
+let globalCache: VibecheckCache | null = null;
+
+export function getGlobalCache(): VibecheckCache {
+  if (!globalCache) {
+    globalCache = new VibecheckCache();
+  }
+  return globalCache;
+}
+
+export function initGlobalCache(config: CacheConfig): void {
+  globalCache = new VibecheckCache(config);
+}
+
+export default {
+  VibecheckCache,
+  getGlobalCache,
+  initGlobalCache,
+};

package/mcp-server/lib/errors.ts

@@ -0,0 +1,346 @@
+/**
+ * Error Handling & Normalization
+ * 
+ * All errors are normalized to ErrorEnvelope format.
+ * No mystery errors - every failure has a code, message, and userAction.
+ */
+
+import { randomUUID } from 'crypto';
+
+/**
+ * Error codes enum
+ */
+export enum ErrorCode {
+  INVALID_INPUT = 'INVALID_INPUT',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  PATH_NOT_FOUND = 'PATH_NOT_FOUND',
+  PATH_OUTSIDE_SANDBOX = 'PATH_OUTSIDE_SANDBOX',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  TIER_REQUIRED = 'TIER_REQUIRED',
+  RATE_LIMITED = 'RATE_LIMITED',
+  TIMEOUT = 'TIMEOUT',
+  CANCELLED = 'CANCELLED',
+  CLI_ERROR = 'CLI_ERROR',
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  NOT_FOUND = 'NOT_FOUND',
+  ALREADY_EXISTS = 'ALREADY_EXISTS',
+  DEPENDENCY_MISSING = 'DEPENDENCY_MISSING',
+  CONFIG_ERROR = 'CONFIG_ERROR',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  TRUTH_FIREWALL_REQUIRED = 'TRUTH_FIREWALL_REQUIRED',
+}
+
+/**
+ * Error envelope structure
+ */
+export interface ErrorEnvelope {
+  ok: false;
+  error: {
+    code: ErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+    retryable: boolean;
+    retryAfterMs?: number;
+    userAction?: string;
+    docsUrl?: string;
+  };
+  requestId: string;
+  timestamp: string;
+}
+
+/**
+ * Success envelope structure
+ */
+export interface SuccessEnvelope<T> {
+  ok: true;
+  data: T;
+  meta?: {
+    cached?: boolean;
+    cacheAge?: number;
+    durationMs?: number;
+    requestId?: string;
+  };
+  timestamp: string;
+}
+
+/**
+ * Custom error class
+ */
+export class VibecheckError extends Error {
+  code: ErrorCode;
+  details?: Record<string, unknown>;
+  retryable: boolean;
+  retryAfterMs?: number;
+  userAction?: string;
+  docsUrl?: string;
+
+  constructor(
+    code: ErrorCode,
+    message: string,
+    options?: {
+      details?: Record<string, unknown>;
+      retryable?: boolean;
+      retryAfterMs?: number;
+      userAction?: string;
+      docsUrl?: string;
+    }
+  ) {
+    super(message);
+    this.name = 'VibecheckError';
+    this.code = code;
+    this.details = options?.details;
+    this.retryable = options?.retryable ?? false;
+    this.retryAfterMs = options?.retryAfterMs;
+    this.userAction = options?.userAction;
+    this.docsUrl = options?.docsUrl;
+  }
+}
+
+/**
+ * Create error envelope from error
+ */
+export function createErrorEnvelope(
+  error: unknown,
+  requestId?: string
+): ErrorEnvelope {
+  const id = requestId || randomUUID();
+  const timestamp = new Date().toISOString();
+
+  if (error instanceof VibecheckError) {
+    return {
+      ok: false,
+      error: {
+        code: error.code,
+        message: error.message,
+        details: error.details,
+        retryable: error.retryable,
+        retryAfterMs: error.retryAfterMs,
+        userAction: error.userAction,
+        docsUrl: error.docsUrl,
+      },
+      requestId: id,
+      timestamp,
+    };
+  }
+
+  // Normalize unknown errors
+  const message = error instanceof Error ? error.message : String(error);
+  
+  // Try to infer error type
+  const inferredCode = inferErrorCode(message);
+  const inferredAction = inferUserAction(inferredCode, message);
+
+  return {
+    ok: false,
+    error: {
+      code: inferredCode,
+      message,
+      retryable: isRetryable(inferredCode),
+      userAction: inferredAction,
+    },
+    requestId: id,
+    timestamp,
+  };
+}
+
+/**
+ * Create success envelope
+ */
+export function createSuccessEnvelope<T>(
+  data: T,
+  options?: {
+    cached?: boolean;
+    cacheAge?: number;
+    durationMs?: number;
+    requestId?: string;
+  }
+): SuccessEnvelope<T> {
+  return {
+    ok: true,
+    data,
+    meta: options ? {
+      cached: options.cached,
+      cacheAge: options.cacheAge,
+      durationMs: options.durationMs,
+      requestId: options.requestId,
+    } : undefined,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Infer error code from message
+ */
+function inferErrorCode(message: string): ErrorCode {
+  const lower = message.toLowerCase();
+
+  if (lower.includes('timeout') || lower.includes('timed out')) {
+    return ErrorCode.TIMEOUT;
+  }
+  if (lower.includes('enoent') || lower.includes('not found') || lower.includes('does not exist')) {
+    return ErrorCode.PATH_NOT_FOUND;
+  }
+  if (lower.includes('eperm') || lower.includes('eacces') || lower.includes('permission')) {
+    return ErrorCode.PERMISSION_DENIED;
+  }
+  if (lower.includes('rate limit') || lower.includes('too many requests')) {
+    return ErrorCode.RATE_LIMITED;
+  }
+  if (lower.includes('cancelled') || lower.includes('aborted')) {
+    return ErrorCode.CANCELLED;
+  }
+  if (lower.includes('validation') || lower.includes('invalid')) {
+    return ErrorCode.VALIDATION_ERROR;
+  }
+  if (lower.includes('tier') || lower.includes('upgrade') || lower.includes('subscription')) {
+    return ErrorCode.TIER_REQUIRED;
+  }
+  if (lower.includes('network') || lower.includes('econnrefused') || lower.includes('enotfound')) {
+    return ErrorCode.NETWORK_ERROR;
+  }
+  if (lower.includes('missing') && lower.includes('depend')) {
+    return ErrorCode.DEPENDENCY_MISSING;
+  }
+  if (lower.includes('config')) {
+    return ErrorCode.CONFIG_ERROR;
+  }
+  if (lower.includes('truth') && lower.includes('firewall')) {
+    return ErrorCode.TRUTH_FIREWALL_REQUIRED;
+  }
+
+  return ErrorCode.INTERNAL_ERROR;
+}
+
+/**
+ * Infer user action from error
+ */
+function inferUserAction(code: ErrorCode, message: string): string {
+  switch (code) {
+    case ErrorCode.PATH_NOT_FOUND:
+      return 'Check that the path exists and is spelled correctly';
+    case ErrorCode.PATH_OUTSIDE_SANDBOX:
+      return 'Provide a path within your project workspace';
+    case ErrorCode.PERMISSION_DENIED:
+      return 'Check file permissions or run with appropriate access';
+    case ErrorCode.TIER_REQUIRED:
+      return 'Upgrade your plan at https://vibecheck.dev/pricing';
+    case ErrorCode.RATE_LIMITED:
+      return 'Wait a moment and try again';
+    case ErrorCode.TIMEOUT:
+      return 'Try again with a smaller scope or increase timeout';
+    case ErrorCode.DEPENDENCY_MISSING:
+      return 'Run npm install or check your package.json';
+    case ErrorCode.CONFIG_ERROR:
+      return 'Check your vibecheck configuration file';
+    case ErrorCode.NETWORK_ERROR:
+      return 'Check your network connection and try again';
+    case ErrorCode.TRUTH_FIREWALL_REQUIRED:
+      return 'Call vibecheck.get_truthpack or vibecheck.validate_claim first';
+    case ErrorCode.VALIDATION_ERROR:
+      return 'Check your input parameters against the tool schema';
+    default:
+      return 'If this persists, please report at https://github.com/vibecheckai/vibecheck/issues';
+  }
+}
+
+/**
+ * Check if error is retryable
+ */
+function isRetryable(code: ErrorCode): boolean {
+  switch (code) {
+    case ErrorCode.TIMEOUT:
+    case ErrorCode.RATE_LIMITED:
+    case ErrorCode.NETWORK_ERROR:
+      return true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Error factory functions for common cases
+ */
+export const Errors = {
+  invalidInput(message: string, details?: Record<string, unknown>) {
+    return new VibecheckError(ErrorCode.INVALID_INPUT, message, {
+      details,
+      userAction: 'Check your input parameters',
+    });
+  },
+
+  pathNotFound(path: string) {
+    return new VibecheckError(ErrorCode.PATH_NOT_FOUND, `Path not found: ${path}`, {
+      details: { path },
+      userAction: 'Check that the path exists',
+    });
+  },
+
+  pathOutsideSandbox(path: string, workspace: string) {
+    return new VibecheckError(
+      ErrorCode.PATH_OUTSIDE_SANDBOX,
+      `Path '${path}' is outside the allowed workspace`,
+      {
+        details: { path, workspace },
+        userAction: 'Provide a path within your project workspace',
+      }
+    );
+  },
+
+  tierRequired(feature: string, requiredTier: string, currentTier: string) {
+    return new VibecheckError(
+      ErrorCode.TIER_REQUIRED,
+      `${feature} requires ${requiredTier} tier`,
+      {
+        details: { feature, requiredTier, currentTier },
+        userAction: `Upgrade to ${requiredTier} at https://vibecheck.dev/pricing`,
+        docsUrl: 'https://vibecheck.dev/pricing',
+      }
+    );
+  },
+
+  timeout(timeoutMs: number) {
+    return new VibecheckError(
+      ErrorCode.TIMEOUT,
+      `Operation timed out after ${timeoutMs}ms`,
+      {
+        retryable: true,
+        retryAfterMs: 5000,
+        userAction: 'Try with a smaller scope or increase timeout',
+      }
+    );
+  },
+
+  rateLimited(retryAfterMs: number) {
+    return new VibecheckError(ErrorCode.RATE_LIMITED, 'Rate limit exceeded', {
+      retryable: true,
+      retryAfterMs,
+      userAction: `Wait ${Math.ceil(retryAfterMs / 1000)} seconds and try again`,
+    });
+  },
+
+  cliError(message: string, exitCode?: number) {
+    return new VibecheckError(ErrorCode.CLI_ERROR, message, {
+      details: { exitCode },
+      userAction: 'Check the CLI output for details',
+    });
+  },
+
+  truthFirewallRequired() {
+    return new VibecheckError(
+      ErrorCode.TRUTH_FIREWALL_REQUIRED,
+      'Truth firewall requires claim validation before high-impact tools',
+      {
+        userAction: 'Call vibecheck.get_truthpack or vibecheck.validate_claim first',
+        docsUrl: 'https://vibecheck.dev/docs/truth-firewall',
+      }
+    );
+  },
+};
+
+export default {
+  ErrorCode,
+  VibecheckError,
+  Errors,
+  createErrorEnvelope,
+  createSuccessEnvelope,
+};