monomind 1.10.1 → 1.10.2

package/packages/@monomind/cli/dist/src/production/monitoring.js

@@ -0,0 +1,360 @@
+/**
+ * Production Monitoring and Observability
+ *
+ * Provides monitoring hooks for:
+ * - Request/response metrics
+ * - Error tracking
+ * - Performance monitoring
+ * - Health checks
+ * - Alerting
+ *
+ * @module @monomind/cli/production/monitoring
+ */
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_CONFIG = {
+    enabled: true,
+    retentionMs: 3600000, // 1 hour
+    maxMetrics: 100000,
+    samplingRate: 1.0,
+    alertThresholds: {
+        'error_rate': { warning: 0.05, critical: 0.1 },
+        'response_time_ms': { warning: 1000, critical: 5000 },
+        'active_requests': { warning: 100, critical: 500 },
+    },
+    healthCheckIntervalMs: 30000,
+    globalLabels: {},
+};
+// ============================================================================
+// Monitoring Implementation
+// ============================================================================
+export class MonitoringHooks {
+    config;
+    metrics = [];
+    responseTimes = [];
+    alerts = [];
+    healthStatus;
+    startTime = Date.now();
+    activeRequests = 0;
+    requestCount = 0;
+    errorCount = 0;
+    healthChecks = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.healthStatus = {
+            healthy: true,
+            checks: {},
+            timestamp: Date.now(),
+        };
+    }
+    // ============================================================================
+    // Metrics Collection
+    // ============================================================================
+    /**
+     * Record a counter metric
+     */
+    counter(name, value = 1, labels = {}) {
+        this.recordMetric(name, 'counter', value, labels);
+    }
+    /**
+     * Record a gauge metric
+     */
+    gauge(name, value, labels = {}) {
+        this.recordMetric(name, 'gauge', value, labels);
+    }
+    /**
+     * Record a histogram metric
+     */
+    histogram(name, value, labels = {}) {
+        this.recordMetric(name, 'histogram', value, labels);
+    }
+    /**
+     * Record a metric event
+     */
+    recordMetric(name, type, value, labels) {
+        if (!this.config.enabled)
+            return;
+        // Apply sampling
+        if (Math.random() > this.config.samplingRate)
+            return;
+        const event = {
+            name,
+            type,
+            value,
+            labels: { ...this.config.globalLabels, ...labels },
+            timestamp: Date.now(),
+        };
+        this.metrics.push(event);
+        // Check alerts
+        this.checkAlerts(name, value);
+        // Cleanup old metrics
+        this.cleanupMetrics();
+    }
+    // ============================================================================
+    // Request Tracking
+    // ============================================================================
+    /**
+     * Start tracking a request
+     */
+    startRequest(requestId) {
+        this.activeRequests++;
+        this.requestCount++;
+        const startTime = Date.now();
+        this.counter('request_started', 1, {});
+        // Return end function
+        return () => {
+            this.activeRequests--;
+            const duration = Date.now() - startTime;
+            this.responseTimes.push(duration);
+            this.histogram('response_time_ms', duration, {});
+            // Keep only last 1000 response times
+            if (this.responseTimes.length > 1000) {
+                this.responseTimes = this.responseTimes.slice(-1000);
+            }
+        };
+    }
+    /**
+     * Record an error
+     */
+    recordError(error, labels = {}) {
+        this.errorCount++;
+        this.counter('error', 1, {
+            ...labels,
+            errorType: error.name,
+        });
+    }
+    // ============================================================================
+    // Health Checks
+    // ============================================================================
+    /**
+     * Register a health check
+     */
+    registerHealthCheck(name, check) {
+        this.healthChecks.set(name, check);
+    }
+    /**
+     * Run all health checks
+     */
+    async runHealthChecks() {
+        const checks = {};
+        let allHealthy = true;
+        for (const [name, check] of this.healthChecks) {
+            const startTime = Date.now();
+            try {
+                const result = await check();
+                checks[name] = {
+                    status: result.healthy ? 'healthy' : 'unhealthy',
+                    message: result.message,
+                    lastCheck: Date.now(),
+                    responseTimeMs: Date.now() - startTime,
+                };
+                if (!result.healthy)
+                    allHealthy = false;
+            }
+            catch (error) {
+                checks[name] = {
+                    status: 'unhealthy',
+                    message: error.message,
+                    lastCheck: Date.now(),
+                    responseTimeMs: Date.now() - startTime,
+                };
+                allHealthy = false;
+            }
+        }
+        this.healthStatus = {
+            healthy: allHealthy,
+            checks,
+            timestamp: Date.now(),
+        };
+        return this.healthStatus;
+    }
+    /**
+     * Get current health status
+     */
+    getHealthStatus() {
+        return this.healthStatus;
+    }
+    // ============================================================================
+    // Performance Metrics
+    // ============================================================================
+    /**
+     * Get performance metrics
+     */
+    getPerformanceMetrics() {
+        const sortedTimes = [...this.responseTimes].sort((a, b) => a - b);
+        const count = sortedTimes.length;
+        const percentile = (p) => {
+            if (count === 0)
+                return 0;
+            const index = Math.ceil(count * p) - 1;
+            return sortedTimes[Math.min(index, count - 1)];
+        };
+        const avgResponseTime = count > 0
+            ? sortedTimes.reduce((a, b) => a + b, 0) / count
+            : 0;
+        return {
+            requestCount: this.requestCount,
+            errorCount: this.errorCount,
+            errorRate: this.requestCount > 0 ? this.errorCount / this.requestCount : 0,
+            avgResponseTimeMs: Math.round(avgResponseTime),
+            p50ResponseTimeMs: percentile(0.5),
+            p95ResponseTimeMs: percentile(0.95),
+            p99ResponseTimeMs: percentile(0.99),
+            activeRequests: this.activeRequests,
+            uptime: Date.now() - this.startTime,
+        };
+    }
+    // ============================================================================
+    // Alerting
+    // ============================================================================
+    /**
+     * Get active alerts
+     */
+    getAlerts(level) {
+        let filtered = this.alerts.filter(a => !a.acknowledged);
+        if (level) {
+            filtered = filtered.filter(a => a.level === level);
+        }
+        return filtered;
+    }
+    /**
+     * Acknowledge an alert
+     */
+    acknowledgeAlert(alertId) {
+        const alert = this.alerts.find(a => a.id === alertId);
+        if (alert) {
+            alert.acknowledged = true;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clear all alerts
+     */
+    clearAlerts() {
+        this.alerts = [];
+    }
+    // ============================================================================
+    // Data Export
+    // ============================================================================
+    /**
+     * Get metrics for a specific name
+     */
+    getMetrics(name, since) {
+        let filtered = this.metrics.filter(m => m.name === name);
+        if (since) {
+            filtered = filtered.filter(m => m.timestamp >= since);
+        }
+        return filtered;
+    }
+    /**
+     * Get all metrics summary
+     */
+    getMetricsSummary() {
+        const summary = {};
+        for (const metric of this.metrics) {
+            if (!summary[metric.name]) {
+                summary[metric.name] = { count: 0, sum: 0, lastValue: 0 };
+            }
+            summary[metric.name].count++;
+            summary[metric.name].sum += metric.value;
+            summary[metric.name].lastValue = metric.value;
+        }
+        const result = {};
+        for (const [name, data] of Object.entries(summary)) {
+            result[name] = {
+                count: data.count,
+                lastValue: data.lastValue,
+                avgValue: data.count > 0 ? data.sum / data.count : 0,
+            };
+        }
+        return result;
+    }
+    /**
+     * Reset all metrics
+     */
+    reset() {
+        this.metrics = [];
+        this.responseTimes = [];
+        this.alerts = [];
+        this.requestCount = 0;
+        this.errorCount = 0;
+        this.activeRequests = 0;
+        this.startTime = Date.now();
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    checkAlerts(name, value) {
+        const thresholds = this.config.alertThresholds[name];
+        if (!thresholds)
+            return;
+        let level = null;
+        let threshold = 0;
+        if (value >= thresholds.critical) {
+            level = 'critical';
+            threshold = thresholds.critical;
+        }
+        else if (value >= thresholds.warning) {
+            level = 'warning';
+            threshold = thresholds.warning;
+        }
+        if (level) {
+            // Check if we already have a recent alert for this metric
+            const recentAlert = this.alerts.find(a => a.metric === name &&
+                !a.acknowledged &&
+                Date.now() - a.timestamp < 60000);
+            if (!recentAlert) {
+                this.alerts.push({
+                    id: `alert_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+                    level,
+                    metric: name,
+                    message: `${name} exceeded ${level} threshold: ${value} >= ${threshold}`,
+                    value,
+                    threshold,
+                    timestamp: Date.now(),
+                    acknowledged: false,
+                });
+            }
+        }
+    }
+    cleanupMetrics() {
+        const now = Date.now();
+        const cutoff = now - this.config.retentionMs;
+        // Remove old metrics
+        this.metrics = this.metrics.filter(m => m.timestamp > cutoff);
+        // Limit total metrics
+        if (this.metrics.length > this.config.maxMetrics) {
+            this.metrics = this.metrics.slice(-this.config.maxMetrics);
+        }
+        // Remove old acknowledged alerts
+        this.alerts = this.alerts.filter(a => !a.acknowledged || Date.now() - a.timestamp < 300000);
+        // Cap total alerts to prevent unbounded growth
+        const MAX_ALERTS = 500;
+        if (this.alerts.length > MAX_ALERTS) {
+            this.alerts = this.alerts.slice(-MAX_ALERTS);
+        }
+    }
+}
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+let defaultMonitor = null;
+/**
+ * Create or get the default monitor
+ */
+export function createMonitor(config) {
+    if (!defaultMonitor) {
+        defaultMonitor = new MonitoringHooks(config);
+    }
+    return defaultMonitor;
+}
+/**
+ * Get the default monitor
+ */
+export function getMonitor() {
+    return createMonitor();
+}
+export default MonitoringHooks;
+//# sourceMappingURL=monitoring.js.map

package/packages/@monomind/cli/dist/src/production/rate-limiter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Production Rate Limiting
+ *
+ * Provides token bucket rate limiting with:
+ * - Per-operation limits
+ * - Per-user/agent limits
+ * - Burst allowance
+ * - Sliding window tracking
+ *
+ * @module @monoes/cli/production/rate-limiter
+ */
+export interface RateLimiterConfig {
+    maxRequests: number;
+    windowMs: number;
+    burstMultiplier: number;
+    whitelist: string[];
+    operationLimits: Record<string, {
+        maxRequests: number;
+        windowMs: number;
+    }>;
+    perUserLimits: boolean;
+    maxTrackedUsers: number;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+    retryAfterMs?: number;
+}
+export declare class RateLimiter {
+    private config;
+    private buckets;
+    private globalBucket;
+    constructor(config?: Partial<RateLimiterConfig>);
+    /**
+     * Check if a request is allowed
+     */
+    check(operation: string, userId?: string): RateLimitResult;
+    /**
+     * Consume a token (use after successful request)
+     */
+    consume(operation: string, userId?: string): boolean;
+    /**
+     * Get current rate limit status
+     */
+    getStatus(operation: string, userId?: string): {
+        current: number;
+        limit: number;
+        remaining: number;
+        resetAt: number;
+    };
+    /**
+     * Reset limits for a specific key
+     */
+    reset(operation: string, userId?: string): void;
+    /**
+     * Reset all limits
+     */
+    resetAll(): void;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        totalBuckets: number;
+        activeUsers: number;
+        mostLimitedOperations: Array<{
+            operation: string;
+            requests: number;
+        }>;
+    };
+    private getLimits;
+    private createBucket;
+    private cleanupBuckets;
+}
+/**
+ * Create a rate limiter with default config
+ */
+export declare function createRateLimiter(config?: Partial<RateLimiterConfig>): RateLimiter;
+export default RateLimiter;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/packages/@monomind/cli/dist/src/production/rate-limiter.js

@@ -0,0 +1,209 @@
+/**
+ * Production Rate Limiting
+ *
+ * Provides token bucket rate limiting with:
+ * - Per-operation limits
+ * - Per-user/agent limits
+ * - Burst allowance
+ * - Sliding window tracking
+ *
+ * @module @monomind/cli/production/rate-limiter
+ */
+// ============================================================================
+// Rate Limiter
+// ============================================================================
+const DEFAULT_CONFIG = {
+    maxRequests: 100,
+    windowMs: 60000, // 1 minute
+    burstMultiplier: 1.5,
+    whitelist: [],
+    operationLimits: {},
+    perUserLimits: true,
+    maxTrackedUsers: 10000,
+};
+export class RateLimiter {
+    config;
+    buckets = new Map();
+    globalBucket;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.globalBucket = this.createBucket();
+    }
+    /**
+     * Check if a request is allowed
+     */
+    check(operation, userId) {
+        // Check whitelist
+        if (this.config.whitelist.includes(operation)) {
+            return { allowed: true, remaining: Infinity, resetAt: 0 };
+        }
+        // Get limits for this operation
+        const limits = this.getLimits(operation);
+        const now = Date.now();
+        // Get or create bucket
+        const bucketKey = userId && this.config.perUserLimits
+            ? `${operation}:${userId}`
+            : `global:${operation}`;
+        let bucket = this.buckets.get(bucketKey);
+        if (!bucket) {
+            bucket = this.createBucket();
+            this.buckets.set(bucketKey, bucket);
+            this.cleanupBuckets();
+        }
+        // Clean old requests from sliding window
+        bucket.requests = bucket.requests.filter(t => t > now - limits.windowMs);
+        // Calculate remaining — uses base maxRequests (consistent with getStatus())
+        const remaining = limits.maxRequests - bucket.requests.length;
+        if (remaining <= 0) {
+            // Rate limited
+            const oldestRequest = bucket.requests[0];
+            const resetAt = oldestRequest + limits.windowMs;
+            const retryAfterMs = resetAt - now;
+            return {
+                allowed: false,
+                remaining: 0,
+                resetAt,
+                retryAfterMs: Math.max(0, retryAfterMs),
+            };
+        }
+        // Allow request
+        bucket.requests.push(now);
+        return {
+            allowed: true,
+            remaining: remaining - 1,
+            resetAt: now + limits.windowMs,
+        };
+    }
+    /**
+     * Consume a token (use after successful request)
+     */
+    consume(operation, userId) {
+        const result = this.check(operation, userId);
+        return result.allowed;
+    }
+    /**
+     * Get current rate limit status
+     */
+    getStatus(operation, userId) {
+        const limits = this.getLimits(operation);
+        const bucketKey = userId && this.config.perUserLimits
+            ? `${operation}:${userId}`
+            : `global:${operation}`;
+        const bucket = this.buckets.get(bucketKey);
+        const now = Date.now();
+        if (!bucket) {
+            return {
+                current: 0,
+                limit: limits.maxRequests,
+                remaining: limits.maxRequests,
+                resetAt: now + limits.windowMs,
+            };
+        }
+        // Clean old requests
+        const validRequests = bucket.requests.filter(t => t > now - limits.windowMs);
+        return {
+            current: validRequests.length,
+            limit: limits.maxRequests,
+            remaining: Math.max(0, limits.maxRequests - validRequests.length),
+            resetAt: validRequests.length > 0
+                ? validRequests[0] + limits.windowMs
+                : now + limits.windowMs,
+        };
+    }
+    /**
+     * Reset limits for a specific key
+     */
+    reset(operation, userId) {
+        const bucketKey = userId && this.config.perUserLimits
+            ? `${operation}:${userId}`
+            : `global:${operation}`;
+        this.buckets.delete(bucketKey);
+    }
+    /**
+     * Reset all limits
+     */
+    resetAll() {
+        this.buckets.clear();
+        this.globalBucket = this.createBucket();
+    }
+    /**
+     * Get statistics
+     */
+    getStats() {
+        const operationCounts = new Map();
+        const users = new Set();
+        for (const [key, bucket] of this.buckets) {
+            const colonIdx = key.indexOf(':');
+            const prefix = colonIdx >= 0 ? key.slice(0, colonIdx) : key;
+            const suffix = colonIdx >= 0 ? key.slice(colonIdx + 1) : undefined;
+            const operation = prefix === 'global' ? (suffix ?? prefix) : prefix;
+            const userId = prefix === 'global' ? undefined : suffix;
+            if (userId)
+                users.add(userId);
+            const current = operationCounts.get(operation) || 0;
+            operationCounts.set(operation, current + bucket.requests.length);
+        }
+        const mostLimited = Array.from(operationCounts.entries())
+            .map(([operation, requests]) => ({ operation, requests }))
+            .sort((a, b) => b.requests - a.requests)
+            .slice(0, 10);
+        return {
+            totalBuckets: this.buckets.size,
+            activeUsers: users.size,
+            mostLimitedOperations: mostLimited,
+        };
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    getLimits(operation) {
+        return this.config.operationLimits[operation] || {
+            maxRequests: this.config.maxRequests,
+            windowMs: this.config.windowMs,
+        };
+    }
+    createBucket() {
+        return {
+            tokens: this.config.maxRequests,
+            lastRefill: Date.now(),
+            requests: [],
+        };
+    }
+    cleanupBuckets() {
+        if (this.buckets.size <= this.config.maxTrackedUsers)
+            return;
+        const now = Date.now();
+        const target = Math.floor(this.config.maxTrackedUsers * 0.8);
+        // First pass: delete buckets with no recent activity (cheap LRU)
+        for (const [key, bucket] of this.buckets) {
+            if (this.buckets.size <= target)
+                break;
+            const recent = bucket.requests.filter(t => t > now - this.config.windowMs * 2);
+            if (recent.length === 0)
+                this.buckets.delete(key);
+        }
+        if (this.buckets.size <= target)
+            return;
+        // Second pass: even active buckets get evicted if we are still over the cap.
+        // Eviction order: oldest first-request timestamp wins (true LRU on activity).
+        const entries = Array.from(this.buckets.entries())
+            .map(([key, bucket]) => ({ key, oldest: bucket.requests[0] ?? 0 }))
+            .sort((a, b) => a.oldest - b.oldest);
+        for (const { key } of entries) {
+            if (this.buckets.size <= target)
+                break;
+            this.buckets.delete(key);
+        }
+    }
+}
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+/**
+ * Create a rate limiter with default config
+ */
+export function createRateLimiter(config) {
+    return new RateLimiter(config);
+}
+export default RateLimiter;
+//# sourceMappingURL=rate-limiter.js.map

package/packages/@monomind/cli/dist/src/production/retry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Production Retry Mechanisms
+ *
+ * Provides retry with:
+ * - Exponential backoff
+ * - Jitter
+ * - Per-error-type configuration
+ * - Circuit breaker integration
+ *
+ * @module @monoes/cli/production/retry
+ */
+export interface RetryConfig {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+    jitter: number;
+    nonRetryableErrors: string[];
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    onRetry?: (error: Error, attempt: number, delayMs: number) => void;
+}
+export interface RetryResult<T> {
+    success: boolean;
+    result?: T;
+    error?: Error;
+    attempts: number;
+    totalTimeMs: number;
+    retryHistory: Array<{
+        attempt: number;
+        error: string;
+        delayMs: number;
+    }>;
+}
+export type RetryStrategy = 'exponential' | 'linear' | 'constant' | 'fibonacci';
+/**
+ * Execute a function with retry logic
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>, strategy?: RetryStrategy): Promise<RetryResult<T>>;
+/**
+ * Create a retryable version of a function
+ */
+export declare function makeRetryable<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, config?: Partial<RetryConfig>, strategy?: RetryStrategy): (...args: Parameters<T>) => Promise<RetryResult<Awaited<ReturnType<T>>>>;
+/**
+ * Retry decorator for class methods
+ */
+export declare function Retryable(config?: Partial<RetryConfig>, strategy?: RetryStrategy): (_target: unknown, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export default withRetry;
+//# sourceMappingURL=retry.d.ts.map