@claude-flow/cli 3.32.3 → 3.32.5

package/dist/src/production/error-handler.js

@@ -0,0 +1,299 @@
+/**
+ * Production Error Handling
+ *
+ * Provides standardized error handling with:
+ * - Error classification
+ * - Sanitization (no sensitive data leak)
+ * - Structured error responses
+ * - Error aggregation and reporting
+ *
+ * @module @claude-flow/cli/production/error-handler
+ */
+// ============================================================================
+// Error Classification
+// ============================================================================
+const ERROR_PATTERNS = {
+    validation: [
+        /invalid/i,
+        /required/i,
+        /missing/i,
+        /must be/i,
+        /cannot be/i,
+        /validation/i,
+    ],
+    authentication: [
+        /unauthorized/i,
+        /unauthenticated/i,
+        /not authenticated/i,
+        /invalid token/i,
+        /expired token/i,
+    ],
+    authorization: [
+        /forbidden/i,
+        /permission denied/i,
+        /access denied/i,
+        /not allowed/i,
+    ],
+    not_found: [
+        /not found/i,
+        /does not exist/i,
+        /no such/i,
+        /unknown/i,
+    ],
+    rate_limit: [
+        /rate limit/i,
+        /too many requests/i,
+        /throttled/i,
+    ],
+    timeout: [
+        /timeout/i,
+        /timed out/i,
+        /deadline/i,
+    ],
+    circuit_open: [
+        /circuit open/i,
+        /service unavailable/i,
+        /temporarily unavailable/i,
+    ],
+    external_service: [
+        /ECONNREFUSED/i,
+        /ENOTFOUND/i,
+        /ETIMEDOUT/i,
+        /network/i,
+        /connection/i,
+    ],
+    internal: [
+        /internal/i,
+        /unexpected/i,
+    ],
+    unknown: [],
+};
+const RETRYABLE_CATEGORIES = [
+    'timeout',
+    'external_service',
+    'rate_limit',
+    'circuit_open',
+];
+// Sensitive keys to sanitize
+const SENSITIVE_KEYS = [
+    'password',
+    'token',
+    'api_key',
+    'apiKey',
+    'secret',
+    'authorization',
+    'bearer',
+    'credential',
+    'private',
+];
+// ============================================================================
+// Error Handler
+// ============================================================================
+const DEFAULT_CONFIG = {
+    includeStack: process.env.NODE_ENV !== 'production',
+    sanitize: true,
+    reportToMonitoring: true,
+    maxErrorsPerMinute: 100,
+    errorCategories: {},
+};
+export class ErrorHandler {
+    config;
+    errorCounts = new Map();
+    errorLog = [];
+    maxLogSize = 1000;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Classify an error into a category
+     */
+    classifyError(error) {
+        const message = typeof error === 'string' ? error : error.message;
+        for (const [category, patterns] of Object.entries(ERROR_PATTERNS)) {
+            for (const pattern of patterns) {
+                if (pattern.test(message)) {
+                    return category;
+                }
+            }
+        }
+        return 'unknown';
+    }
+    /**
+     * Check if an error category is retryable
+     */
+    isRetryable(category) {
+        return RETRYABLE_CATEGORIES.includes(category);
+    }
+    /**
+     * Sanitize input to remove sensitive data
+     */
+    sanitize(input) {
+        if (!this.config.sanitize)
+            return input;
+        const sanitized = {};
+        for (const [key, value] of Object.entries(input)) {
+            const lowerKey = key.toLowerCase();
+            const isSensitive = SENSITIVE_KEYS.some(sk => lowerKey.includes(sk.toLowerCase()));
+            if (isSensitive) {
+                sanitized[key] = '[REDACTED]';
+            }
+            else if (typeof value === 'object' && value !== null) {
+                sanitized[key] = this.sanitize(value);
+            }
+            else {
+                sanitized[key] = value;
+            }
+        }
+        return sanitized;
+    }
+    /**
+     * Handle an error and return a structured response
+     */
+    handle(error, context = {}) {
+        const message = typeof error === 'string' ? error : error.message;
+        const category = this.classifyError(error);
+        const retryable = this.isRetryable(category);
+        const now = new Date().toISOString();
+        // Track error counts for rate limiting
+        this.trackError(category);
+        // Build structured error
+        const structured = {
+            success: false,
+            error: {
+                code: this.getErrorCode(category),
+                message: this.sanitizeMessage(message),
+                category,
+                retryable,
+                retryAfterMs: retryable ? this.getRetryDelay(category) : undefined,
+            },
+            context: context.input
+                ? { ...context, input: this.sanitize(context.input) }
+                : context,
+            timestamp: now,
+        };
+        // Include stack trace in non-production
+        if (this.config.includeStack && error instanceof Error && error.stack) {
+            structured.error.details = { stack: error.stack };
+        }
+        // Log error
+        this.logError(structured);
+        return structured;
+    }
+    /**
+     * Wrap a handler with error handling
+     */
+    wrap(handler, context) {
+        return (async (...args) => {
+            try {
+                return await handler(...args);
+            }
+            catch (error) {
+                return this.handle(error, {
+                    ...context,
+                    input: args[0],
+                });
+            }
+        });
+    }
+    /**
+     * Get error statistics
+     */
+    getStats() {
+        const byCategory = {};
+        for (const error of this.errorLog) {
+            const cat = error.error.category;
+            byCategory[cat] = (byCategory[cat] || 0) + 1;
+        }
+        // Calculate error rate (errors per minute in last 5 minutes)
+        const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+        const recentCount = this.errorLog.filter(e => new Date(e.timestamp).getTime() > fiveMinutesAgo).length;
+        const errorRate = recentCount / 5;
+        return {
+            totalErrors: this.errorLog.length,
+            byCategory,
+            recentErrors: this.errorLog.slice(-10),
+            errorRate,
+        };
+    }
+    /**
+     * Clear error log
+     */
+    clearLog() {
+        this.errorLog = [];
+        this.errorCounts.clear();
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    getErrorCode(category) {
+        const codes = {
+            validation: 'ERR_VALIDATION',
+            authentication: 'ERR_AUTHENTICATION',
+            authorization: 'ERR_AUTHORIZATION',
+            not_found: 'ERR_NOT_FOUND',
+            rate_limit: 'ERR_RATE_LIMIT',
+            timeout: 'ERR_TIMEOUT',
+            circuit_open: 'ERR_CIRCUIT_OPEN',
+            external_service: 'ERR_EXTERNAL_SERVICE',
+            internal: 'ERR_INTERNAL',
+            unknown: 'ERR_UNKNOWN',
+        };
+        return codes[category];
+    }
+    getRetryDelay(category) {
+        const delays = {
+            timeout: 1000,
+            external_service: 2000,
+            rate_limit: 5000,
+            circuit_open: 30000,
+            validation: 0,
+            authentication: 0,
+            authorization: 0,
+            not_found: 0,
+            internal: 0,
+            unknown: 0,
+        };
+        return delays[category];
+    }
+    sanitizeMessage(message) {
+        if (!this.config.sanitize)
+            return message;
+        // Remove potential sensitive data from message
+        let sanitized = message;
+        for (const key of SENSITIVE_KEYS) {
+            const pattern = new RegExp(`${key}[=:]?\\s*["']?[^\\s"']+["']?`, 'gi');
+            sanitized = sanitized.replace(pattern, `${key}=[REDACTED]`);
+        }
+        return sanitized;
+    }
+    trackError(category) {
+        const now = Date.now();
+        const key = category;
+        const entry = this.errorCounts.get(key);
+        if (!entry || now > entry.resetAt) {
+            this.errorCounts.set(key, { count: 1, resetAt: now + 60000 });
+        }
+        else {
+            entry.count++;
+        }
+    }
+    logError(error) {
+        this.errorLog.push(error);
+        // Trim log if too large
+        if (this.errorLog.length > this.maxLogSize) {
+            this.errorLog = this.errorLog.slice(-this.maxLogSize / 2);
+        }
+    }
+}
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+const defaultHandler = new ErrorHandler();
+/**
+ * Wrap a handler with error handling (convenience function)
+ */
+export function withErrorHandling(handler, context = {}) {
+    return defaultHandler.wrap(handler, context);
+}
+export default ErrorHandler;
+//# sourceMappingURL=error-handler.js.map

package/dist/src/production/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * V3 Production Hardening Module
+ *
+ * Provides production-grade utilities:
+ * - Error handling middleware
+ * - Rate limiting
+ * - Retry mechanisms with exponential backoff
+ * - Circuit breaker pattern
+ * - Monitoring and observability hooks
+ *
+ * @module @claude-flow/cli/production
+ */
+export { ErrorHandler, withErrorHandling } from './error-handler.js';
+export type { ErrorContext, ErrorHandlerConfig } from './error-handler.js';
+export { RateLimiter, createRateLimiter } from './rate-limiter.js';
+export type { RateLimiterConfig, RateLimitResult } from './rate-limiter.js';
+export { withRetry } from './retry.js';
+export type { RetryConfig, RetryResult, RetryStrategy } from './retry.js';
+export { CircuitBreaker } from './circuit-breaker.js';
+export type { CircuitBreakerConfig, CircuitState } from './circuit-breaker.js';
+export { MonitoringHooks, createMonitor } from './monitoring.js';
+export type { MonitorConfig, MetricEvent } from './monitoring.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/production/index.js

@@ -0,0 +1,18 @@
+/**
+ * V3 Production Hardening Module
+ *
+ * Provides production-grade utilities:
+ * - Error handling middleware
+ * - Rate limiting
+ * - Retry mechanisms with exponential backoff
+ * - Circuit breaker pattern
+ * - Monitoring and observability hooks
+ *
+ * @module @claude-flow/cli/production
+ */
+export { ErrorHandler, withErrorHandling } from './error-handler.js';
+export { RateLimiter, createRateLimiter } from './rate-limiter.js';
+export { withRetry } from './retry.js';
+export { CircuitBreaker } from './circuit-breaker.js';
+export { MonitoringHooks, createMonitor } from './monitoring.js';
+//# sourceMappingURL=index.js.map

package/dist/src/production/monitoring.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Production Monitoring and Observability
+ *
+ * Provides monitoring hooks for:
+ * - Request/response metrics
+ * - Error tracking
+ * - Performance monitoring
+ * - Health checks
+ * - Alerting
+ *
+ * @module @claude-flow/cli/production/monitoring
+ */
+export type MetricType = 'counter' | 'gauge' | 'histogram' | 'summary';
+export interface MetricEvent {
+    name: string;
+    type: MetricType;
+    value: number;
+    labels: Record<string, string>;
+    timestamp: number;
+}
+export interface MonitorConfig {
+    enabled: boolean;
+    retentionMs: number;
+    maxMetrics: number;
+    samplingRate: number;
+    alertThresholds: Record<string, {
+        warning: number;
+        critical: number;
+    }>;
+    healthCheckIntervalMs: number;
+    reportingEndpoint?: string;
+    globalLabels: Record<string, string>;
+}
+export interface HealthStatus {
+    healthy: boolean;
+    checks: Record<string, {
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        message?: string;
+        lastCheck: number;
+        responseTimeMs?: number;
+    }>;
+    timestamp: number;
+}
+export interface PerformanceMetrics {
+    requestCount: number;
+    errorCount: number;
+    errorRate: number;
+    avgResponseTimeMs: number;
+    p50ResponseTimeMs: number;
+    p95ResponseTimeMs: number;
+    p99ResponseTimeMs: number;
+    activeRequests: number;
+    uptime: number;
+}
+type AlertLevel = 'info' | 'warning' | 'critical';
+interface Alert {
+    id: string;
+    level: AlertLevel;
+    metric: string;
+    message: string;
+    value: number;
+    threshold: number;
+    timestamp: number;
+    acknowledged: boolean;
+}
+export declare class MonitoringHooks {
+    private config;
+    private metrics;
+    private responseTimes;
+    private alerts;
+    private healthStatus;
+    private startTime;
+    private activeRequests;
+    private requestCount;
+    private errorCount;
+    private healthChecks;
+    constructor(config?: Partial<MonitorConfig>);
+    /**
+     * Record a counter metric
+     */
+    counter(name: string, value?: number, labels?: Record<string, string>): void;
+    /**
+     * Record a gauge metric
+     */
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Record a histogram metric
+     */
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Record a metric event
+     */
+    private recordMetric;
+    /**
+     * Start tracking a request
+     */
+    startRequest(requestId: string): () => void;
+    /**
+     * Record an error
+     */
+    recordError(error: Error, labels?: Record<string, string>): void;
+    /**
+     * Register a health check
+     */
+    registerHealthCheck(name: string, check: () => Promise<{
+        healthy: boolean;
+        message?: string;
+    }>): void;
+    /**
+     * Run all health checks
+     */
+    runHealthChecks(): Promise<HealthStatus>;
+    /**
+     * Get current health status
+     */
+    getHealthStatus(): HealthStatus;
+    /**
+     * Get performance metrics
+     */
+    getPerformanceMetrics(): PerformanceMetrics;
+    /**
+     * Get active alerts
+     */
+    getAlerts(level?: AlertLevel): Alert[];
+    /**
+     * Acknowledge an alert
+     */
+    acknowledgeAlert(alertId: string): boolean;
+    /**
+     * Clear all alerts
+     */
+    clearAlerts(): void;
+    /**
+     * Get metrics for a specific name
+     */
+    getMetrics(name: string, since?: number): MetricEvent[];
+    /**
+     * Get all metrics summary
+     */
+    getMetricsSummary(): Record<string, {
+        count: number;
+        lastValue: number;
+        avgValue: number;
+    }>;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    private checkAlerts;
+    private cleanupMetrics;
+}
+/**
+ * Create or get the default monitor
+ */
+export declare function createMonitor(config?: Partial<MonitorConfig>): MonitoringHooks;
+/**
+ * Get the default monitor
+ */
+export declare function getMonitor(): MonitoringHooks;
+export default MonitoringHooks;
+//# sourceMappingURL=monitoring.d.ts.map