@defai.digital/ax-cli 3.7.2 → 3.8.2

package/dist/mcp/error-formatter.js

@@ -0,0 +1,244 @@
+/**
+ * User-Friendly MCP Error Formatter
+ *
+ * Transforms cryptic Zod validation errors and technical errors into
+ * actionable, user-friendly messages with helpful hints and documentation links.
+ */
+import chalk from 'chalk';
+/**
+ * Format a Zod validation error for MCP server config
+ */
+export function formatMCPConfigError(serverName, error, originalConfig) {
+    const lines = [];
+    lines.push(chalk.red('╭─ MCP Configuration Error ─────────────────────╮'));
+    lines.push(chalk.red(`│ Server: ${chalk.bold(serverName)}`));
+    lines.push(chalk.red('│'));
+    // Group errors by field
+    const errorsByField = new Map();
+    for (const issue of error.issues) {
+        const field = issue.path.length > 0 ? issue.path.join('.') : 'config';
+        const message = issue.message;
+        if (!errorsByField.has(field)) {
+            errorsByField.set(field, []);
+        }
+        errorsByField.get(field).push(message);
+    }
+    // Display errors
+    lines.push(chalk.red('│ Errors:'));
+    for (const [field, messages] of errorsByField.entries()) {
+        lines.push(chalk.red(`│   ❌ Field "${chalk.yellow(field)}":`));
+        messages.forEach(msg => {
+            lines.push(chalk.red(`│      ${msg}`));
+        });
+        // Add helpful hints based on field
+        const hints = getHintsForField(field, originalConfig);
+        if (hints.length > 0) {
+            lines.push(chalk.red(`│      ${chalk.cyan('Hint:')} ${hints[0]}`));
+        }
+    }
+    lines.push(chalk.red('│'));
+    // Add example
+    const example = getExampleConfig(errorsByField, originalConfig);
+    if (example) {
+        lines.push(chalk.red('│ Example correct config:'));
+        example.split('\n').forEach(line => {
+            lines.push(chalk.red(`│   ${chalk.green(line)}`));
+        });
+        lines.push(chalk.red('│'));
+    }
+    // Add documentation link
+    lines.push(chalk.red(`│ ${chalk.blue('📖 Documentation:')} https://docs.ax-cli.dev/mcp/configuration`));
+    lines.push(chalk.red('╰────────────────────────────────────────────────╯'));
+    return lines.join('\n');
+}
+/**
+ * Get helpful hints based on error field
+ */
+function getHintsForField(field, originalConfig) {
+    const hints = [];
+    switch (field) {
+        case 'transport':
+            hints.push('Add "transport": { "type": "stdio", "command": "...", "args": [...] }');
+            if (originalConfig?.command) {
+                hints.push('Legacy format detected. Your "command" field should be inside "transport".');
+            }
+            break;
+        case 'transport.type':
+            hints.push('Valid types: "stdio", "http", "sse", "streamable_http"');
+            break;
+        case 'transport.command':
+            hints.push('Command is required for stdio transport');
+            hints.push('Example: "npx", "node", "python", etc.');
+            break;
+        case 'transport.url':
+            hints.push('URL is required for http/sse transports');
+            hints.push('Example: "https://api.example.com" or "http://localhost:3000"');
+            break;
+        case 'transport.args':
+            hints.push('Args should be an array of strings');
+            hints.push('Example: ["@modelcontextprotocol/server-github"]');
+            break;
+        case 'name':
+            hints.push('Server name is required and should be alphanumeric with hyphens/underscores');
+            hints.push('Example: "github", "my-server", "api_v2"');
+            break;
+        default:
+            if (field.startsWith('transport.')) {
+                hints.push(`Check the ${field.split('.')[1]} field in your transport configuration`);
+            }
+    }
+    return hints;
+}
+/**
+ * Generate example config based on errors
+ */
+function getExampleConfig(errorsByField, originalConfig) {
+    const hasTransportError = Array.from(errorsByField.keys()).some(f => f === 'transport' || f.startsWith('transport.'));
+    if (!hasTransportError) {
+        return null;
+    }
+    // Check if it's likely a stdio config
+    const isStdio = originalConfig?.command || errorsByField.has('transport.command');
+    if (isStdio) {
+        return `{
+  "name": "my-server",
+  "transport": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["@modelcontextprotocol/server-example"],
+    "env": { "API_KEY": "..." }
+  }
+}`;
+    }
+    // Default to HTTP example
+    return `{
+  "name": "my-server",
+  "transport": {
+    "type": "http",
+    "url": "https://api.example.com",
+    "headers": { "Authorization": "Bearer ..." }
+  }
+}`;
+}
+/**
+ * Format a connection error
+ */
+export function formatConnectionError(serverName, error, transportType) {
+    const lines = [];
+    lines.push(chalk.red('╭─ MCP Connection Error ────────────────────────╮'));
+    lines.push(chalk.red(`│ Server: ${chalk.bold(serverName)}`));
+    if (transportType) {
+        lines.push(chalk.red(`│ Transport: ${transportType}`));
+    }
+    lines.push(chalk.red('│'));
+    lines.push(chalk.red(`│ Error: ${error.message}`));
+    lines.push(chalk.red('│'));
+    // Add hints based on error message
+    const hints = getConnectionErrorHints(error, transportType);
+    if (hints.length > 0) {
+        lines.push(chalk.red('│ Troubleshooting:'));
+        hints.forEach(hint => {
+            lines.push(chalk.red(`│   • ${hint}`));
+        });
+        lines.push(chalk.red('│'));
+    }
+    lines.push(chalk.red(`│ ${chalk.blue('🔧 Diagnostics:')} ax-cli mcp test ${serverName}`));
+    lines.push(chalk.red('╰────────────────────────────────────────────────╯'));
+    return lines.join('\n');
+}
+/**
+ * Get hints for connection errors
+ */
+function getConnectionErrorHints(error, transportType) {
+    const hints = [];
+    const message = error.message.toLowerCase();
+    if (message.includes('command not found') || message.includes('enoent')) {
+        hints.push('Command not found. Check if the command is installed and in PATH.');
+        hints.push('Try running the command manually to verify it works.');
+    }
+    else if (message.includes('timeout') || message.includes('timed out')) {
+        hints.push('Connection timed out. Check if the server is running.');
+        hints.push('Verify the URL/command is correct and accessible.');
+    }
+    else if (message.includes('econnrefused') || message.includes('connection refused')) {
+        hints.push('Connection refused. Server may not be running.');
+        hints.push('Check if the server is listening on the correct port.');
+    }
+    else if (message.includes('unauthorized') || message.includes('401')) {
+        hints.push('Authentication failed. Check your API keys/tokens.');
+        hints.push('Verify credentials in environment variables or config.');
+    }
+    else if (message.includes('not found') || message.includes('404')) {
+        hints.push('Endpoint not found. Check the URL path.');
+        hints.push('Verify the server supports MCP protocol.');
+    }
+    else if (message.includes('permission denied') || message.includes('eacces')) {
+        hints.push('Permission denied. Check file/command permissions.');
+        hints.push('You may need to run with sudo or adjust permissions.');
+    }
+    // Transport-specific hints
+    if (transportType === 'stdio' && hints.length === 0) {
+        hints.push('Check if the command is installed: which <command>');
+        hints.push('Verify the args are correct for your command.');
+    }
+    else if ((transportType === 'http' || transportType === 'sse') && hints.length === 0) {
+        hints.push('Verify the server is running: curl <url>');
+        hints.push('Check if the URL is accessible from your network.');
+    }
+    return hints;
+}
+/**
+ * Format a validation error (generic)
+ */
+export function formatValidationError(context, issues) {
+    const lines = [];
+    lines.push(chalk.yellow('╭─ Validation Error ────────────────────────────╮'));
+    lines.push(chalk.yellow(`│ Context: ${context}`));
+    lines.push(chalk.yellow('│'));
+    lines.push(chalk.yellow('│ Issues:'));
+    issues.forEach(({ field, message }) => {
+        lines.push(chalk.yellow(`│   ❌ ${field}: ${message}`));
+    });
+    lines.push(chalk.yellow('╰────────────────────────────────────────────────╯'));
+    return lines.join('\n');
+}
+/**
+ * Format a warning message
+ */
+export function formatWarning(message, details) {
+    const lines = [];
+    lines.push(chalk.yellow(`⚠️  ${message}`));
+    if (details && details.length > 0) {
+        details.forEach(detail => {
+            lines.push(chalk.dim(`   ${detail}`));
+        });
+    }
+    return lines.join('\n');
+}
+/**
+ * Format a success message
+ */
+export function formatSuccess(message, details) {
+    const lines = [];
+    lines.push(chalk.green(`✅ ${message}`));
+    if (details && details.length > 0) {
+        details.forEach(detail => {
+            lines.push(chalk.dim(`   ${detail}`));
+        });
+    }
+    return lines.join('\n');
+}
+/**
+ * Format info message
+ */
+export function formatInfo(message, details) {
+    const lines = [];
+    lines.push(chalk.blue(`ℹ️  ${message}`));
+    if (details && details.length > 0) {
+        details.forEach(detail => {
+            lines.push(chalk.dim(`   ${detail}`));
+        });
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=error-formatter.js.map

package/dist/mcp/error-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.js","sourceRoot":"","sources":["../../src/mcp/error-formatter.ts"],"names":[],"mappings":"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"}

package/dist/mcp/health.d.ts

@@ -66,6 +66,10 @@ export declare class MCPHealthMonitor extends EventEmitter {
      * Stop health monitoring
      */
     stop(): void;
+    /**
+     * Clean up all resources (interval, reconnection manager, event listeners)
+     */
+    dispose(): void;
     /**
      * Perform health checks on all servers
      */
@@ -95,6 +99,7 @@ export declare class MCPHealthMonitor extends EventEmitter {
     getReconnectionManager(): ReconnectionManager;
     /**
      * Calculate percentile from array of values
+     * Returns undefined for empty arrays to distinguish from actual 0 values
      */
     private calculatePercentile;
     /**

package/dist/mcp/health.js

@@ -61,6 +61,19 @@ export class MCPHealthMonitor extends EventEmitter {
             this.healthCheckInterval = null;
         }
     }
+    /**
+     * Clean up all resources (interval, reconnection manager, event listeners)
+     */
+    dispose() {
+        // Stop health monitoring
+        this.stop();
+        // Dispose reconnection manager (clears timers and state)
+        this.reconnectionManager.dispose();
+        // Clear server stats
+        this.serverStats.clear();
+        // Remove all event listeners
+        this.removeAllListeners();
+    }
     /**
      * Perform health checks on all servers
      */
@@ -194,11 +207,18 @@ export class MCPHealthMonitor extends EventEmitter {
     }
     /**
      * Calculate percentile from array of values
+     * Returns undefined for empty arrays to distinguish from actual 0 values
      */
     calculatePercentile(values, percentile) {
+        // EDGE CASE FIX: Handle empty array explicitly
+        if (values.length === 0) {
+            return 0; // Return 0 for empty metrics (no data available)
+        }
         const sorted = [...values].sort((a, b) => a - b);
-        const index = Math.ceil(sorted.length * percentile) - 1;
-        return sorted[index] || 0;
+        // EDGE CASE FIX: Ensure index is never negative
+        const index = Math.max(0, Math.ceil(sorted.length * percentile) - 1);
+        // EDGE CASE FIX: Remove || 0 fallback to preserve actual 0 values
+        return sorted[index];
     }
     /**
      * Get health report for all servers

package/dist/mcp/health.js.map

@@ -1 +1 @@
-{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/mcp/health.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/mcp/health.ts"],"names":[],"mappings":"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"}

package/dist/mcp/invariants.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Runtime Invariant Validation
+ *
+ * This file provides runtime checks for logical invariants that TypeScript
+ * cannot verify at compile-time. These catch the "30% logic bugs" that
+ * slip through type checking.
+ *
+ * Philosophy: Fail Fast & Loud
+ * - Detect bugs immediately when invariant is violated
+ * - Throw descriptive errors with context
+ * - Better to crash than silently corrupt data
+ */
+/**
+ * Invariant check - throws if condition is false
+ *
+ * Use this for conditions that MUST be true for correctness
+ */
+export declare function invariant(condition: boolean, message: string, context?: Record<string, any>): asserts condition;
+/**
+ * Custom error for invariant violations
+ */
+export declare class InvariantViolationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert array is non-empty
+ */
+export declare function assertNonEmpty<T>(array: T[], message?: string): asserts array is [T, ...T[]];
+/**
+ * Assert value is defined (not null or undefined)
+ */
+export declare function assertDefined<T>(value: T | null | undefined, message?: string): asserts value is T;
+/**
+ * Assert number is positive
+ */
+export declare function assertPositive(value: number, message?: string): void;
+/**
+ * Assert number is non-negative
+ */
+export declare function assertNonNegative(value: number, message?: string): void;
+/**
+ * Assert string is non-empty
+ */
+export declare function assertNonEmptyString(value: string, message?: string): void;
+/**
+ * Assert value is within range
+ */
+export declare function assertInRange(value: number, min: number, max: number, message?: string): void;
+/**
+ * Assert map has key
+ */
+export declare function assertHasKey<K, V>(map: Map<K, V>, key: K, message?: string): void;
+/**
+ * Assert object has property
+ */
+export declare function assertHasProperty<T extends object, K extends string>(obj: T, key: K, message?: string): asserts obj is T & Record<K, any>;
+/**
+ * MCP-SPECIFIC INVARIANTS
+ */
+/**
+ * Assert connection state is valid
+ */
+export declare function assertValidConnectionState(state: string, validStates: readonly string[]): void;
+/**
+ * Assert server name is valid format
+ */
+export declare function assertValidServerName(name: string): void;
+/**
+ * Assert migration result is successful
+ */
+export declare function assertMigrationSuccess<T>(result: {
+    success: boolean;
+    value?: T;
+    error?: any;
+}, context?: string): asserts result is {
+    success: true;
+    value: T;
+};
+/**
+ * Assert no duplicate server names
+ */
+export declare function assertNoDuplicates(servers: Array<{
+    name: string;
+}>, message?: string): void;
+/**
+ * Assert mutex is locked
+ */
+export declare function assertMutexLocked(isLocked: boolean, key: string, message?: string): void;
+/**
+ * Assert mutex is unlocked
+ */
+export declare function assertMutexUnlocked(isLocked: boolean, key: string, message?: string): void;
+/**
+ * Assert resource is not disposed
+ */
+export declare function assertNotDisposed(disposed: boolean, resourceName: string, message?: string): void;
+/**
+ * Assert exactly one of multiple conditions is true
+ */
+export declare function assertExactlyOne(conditions: boolean[], labels: string[], message?: string): void;
+/**
+ * Assert at least one condition is true
+ */
+export declare function assertAtLeastOne(conditions: boolean[], labels: string[], message?: string): void;
+/**
+ * Assert config is in expected format
+ */
+export declare function assertConfigFormat(config: any, expectedFormat: 'legacy' | 'modern', serverName: string): void;
+/**
+ * Assert config has required fields
+ */
+export declare function assertConfigHasFields(config: any, requiredFields: string[], serverName: string): void;
+/**
+ * USAGE PATTERNS
+ */
+/**
+ * Pattern 1: Guard functions
+ */
+export declare function guardedConnect(serverName: string, config: any): void;
+/**
+ * Pattern 2: State validation
+ */
+export declare function validateConnectionState(state: string, expectedStates: string[]): void;
+/**
+ * Pattern 3: Pre/Post conditions
+ */
+export declare function criticalOperation(value: number): number;
+/**
+ * Pattern 4: Loop invariants
+ */
+export declare function processServers(servers: Array<{
+    name: string;
+}>): void;
+/**
+ * Pattern 5: Resource management
+ */
+export declare class Resource {
+    private disposed;
+    use(): void;
+    dispose(): void;
+}