@defai.digital/ax-cli 3.14.14 → 3.14.16

package/dist/utils/error-sanitizer.js

@@ -0,0 +1,253 @@
+/**
+ * Error Message Sanitization (REQ-SEC-010)
+ *
+ * Sanitizes error messages to prevent information disclosure
+ * Removes:
+ * - File system paths
+ * - API keys and secrets
+ * - Stack traces (for user-facing errors)
+ * - Internal implementation details
+ *
+ * Security: CVSS 6.5 (Medium Priority)
+ */
+import { homedir } from 'os';
+import { getAuditLogger, AuditCategory } from './audit-logger.js';
+/**
+ * Patterns to detect and sanitize in error messages
+ */
+const SENSITIVE_PATTERNS = {
+    // File paths (Windows and Unix)
+    FILE_PATH: /([A-Za-z]:\\|\/)[^\s"'<>|]+/g,
+    // API keys and tokens (common formats)
+    // Matches patterns like "api_key=XXX", "secret: XXX", "API key: XXX", "bearer XXX"
+    API_KEY: /\b(?:api[_ -]?key|token|secret|password|bearer)[\s:=]+['"]?[a-zA-Z0-9_\-]{16,}['"]?/gi,
+    // Environment variables
+    ENV_VAR: /\$\{?[A-Z_][A-Z0-9_]*\}?/g,
+    // IP addresses (for SSRF protection)
+    IP_ADDRESS: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    // URLs with credentials
+    URL_WITH_CREDS: /https?:\/\/[^:]+:[^@]+@[^\s]+/g,
+    // Stack trace lines
+    STACK_TRACE_LINE: /^\s*at\s+.+\(.+:\d+:\d+\)$/gm,
+    // Home directory references
+    HOME_DIR: new RegExp(homedir().replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'),
+};
+/**
+ * Replacement strings for sanitized content
+ */
+const REPLACEMENTS = {
+    FILE_PATH: '[REDACTED_PATH]',
+    API_KEY: '[REDACTED_KEY]',
+    ENV_VAR: '[REDACTED_ENV]',
+    IP_ADDRESS: '[REDACTED_IP]',
+    URL_WITH_CREDS: '[REDACTED_URL]',
+    STACK_TRACE_LINE: '',
+    HOME_DIR: '[USER_HOME]',
+};
+/**
+ * Error categories for user-friendly messages
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    ErrorCategory["NETWORK"] = "NETWORK";
+    ErrorCategory["FILE_SYSTEM"] = "FILE_SYSTEM";
+    ErrorCategory["VALIDATION"] = "VALIDATION";
+    ErrorCategory["AUTHENTICATION"] = "AUTHENTICATION";
+    ErrorCategory["RATE_LIMIT"] = "RATE_LIMIT";
+    ErrorCategory["API_ERROR"] = "API_ERROR";
+    ErrorCategory["INTERNAL"] = "INTERNAL";
+    ErrorCategory["USER_INPUT"] = "USER_INPUT";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Sanitize error message by removing sensitive information
+ *
+ * @param message - Raw error message
+ * @returns Sanitized message safe for user display
+ */
+export function sanitizeErrorMessage(message) {
+    let sanitized = message;
+    // Remove URLs with credentials first (before FILE_PATH catches them)
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.URL_WITH_CREDS, REPLACEMENTS.URL_WITH_CREDS);
+    // Remove home directory references (before FILE_PATH catches them)
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.HOME_DIR, REPLACEMENTS.HOME_DIR);
+    // Remove file paths
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.FILE_PATH, REPLACEMENTS.FILE_PATH);
+    // Remove API keys and secrets
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.API_KEY, REPLACEMENTS.API_KEY);
+    // Remove environment variables
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.ENV_VAR, REPLACEMENTS.ENV_VAR);
+    // Remove IP addresses
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.IP_ADDRESS, REPLACEMENTS.IP_ADDRESS);
+    return sanitized;
+}
+/**
+ * Sanitize stack trace by removing sensitive paths
+ *
+ * @param stack - Raw stack trace
+ * @returns Sanitized stack trace
+ */
+export function sanitizeStackTrace(stack) {
+    let sanitized = stack;
+    // Remove home directory references first
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.HOME_DIR, REPLACEMENTS.HOME_DIR);
+    // Remove file paths from stack frames
+    sanitized = sanitized.replace(SENSITIVE_PATTERNS.FILE_PATH, REPLACEMENTS.FILE_PATH);
+    return sanitized;
+}
+/**
+ * Remove stack trace entirely (for user-facing errors)
+ *
+ * @param message - Error message with potential stack trace
+ * @returns Message without stack trace
+ */
+export function removeStackTrace(message) {
+    // Split at first "at " (stack trace start)
+    const parts = message.split(/\n\s*at\s+/);
+    return parts[0].trim();
+}
+/**
+ * Categorize error and create user-friendly message
+ *
+ * @param error - Error object
+ * @returns Sanitized error with category and suggestion
+ */
+export function sanitizeError(error) {
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    const message = errorObj.message;
+    // Sanitize the message
+    const sanitizedMessage = sanitizeErrorMessage(removeStackTrace(message));
+    // Determine category and suggestion
+    let category = ErrorCategory.INTERNAL;
+    let suggestion;
+    let code;
+    // Network errors
+    if (message.includes('ENOTFOUND') || message.includes('ECONNREFUSED') || message.includes('fetch failed')) {
+        category = ErrorCategory.NETWORK;
+        suggestion = 'Check your network connection and try again.';
+        code = 'ERR_NETWORK';
+    }
+    // File system errors
+    else if (message.includes('ENOENT') || message.includes('EACCES') || message.includes('EPERM')) {
+        category = ErrorCategory.FILE_SYSTEM;
+        suggestion = 'Check that the file exists and you have permission to access it.';
+        code = 'ERR_FILE_SYSTEM';
+    }
+    // Validation errors
+    else if (message.includes('validation') || message.includes('invalid') || message.includes('required')) {
+        category = ErrorCategory.VALIDATION;
+        suggestion = 'Check your input and try again.';
+        code = 'ERR_VALIDATION';
+    }
+    // Authentication errors
+    else if (message.includes('unauthorized') || message.includes('authentication') || message.includes('API key')) {
+        category = ErrorCategory.AUTHENTICATION;
+        suggestion = 'Check your API key configuration.';
+        code = 'ERR_AUTH';
+    }
+    // Rate limit errors
+    else if (message.includes('rate limit') || message.includes('too many requests')) {
+        category = ErrorCategory.RATE_LIMIT;
+        suggestion = 'Please wait a moment before trying again.';
+        code = 'ERR_RATE_LIMIT';
+    }
+    // API errors
+    else if (message.includes('API') || message.includes('status code')) {
+        category = ErrorCategory.API_ERROR;
+        suggestion = 'The API returned an error. Please try again later.';
+        code = 'ERR_API';
+    }
+    // REQ-SEC-008: Audit log errors with sensitive info detection
+    if (message !== sanitizedMessage) {
+        const auditLogger = getAuditLogger();
+        auditLogger.logWarning({
+            category: AuditCategory.SYSTEM_EVENT,
+            action: 'sensitive_data_in_error',
+            outcome: 'success',
+            details: {
+                category,
+                sanitized: true,
+            },
+        });
+    }
+    return {
+        message: sanitizedMessage,
+        code,
+        category,
+        suggestion,
+        originalError: errorObj,
+    };
+}
+/**
+ * Format sanitized error for user display
+ *
+ * @param sanitizedError - Sanitized error object
+ * @returns Formatted error message
+ */
+export function formatUserError(sanitizedError) {
+    const parts = [];
+    if (sanitizedError.code) {
+        parts.push(`[${sanitizedError.code}]`);
+    }
+    parts.push(sanitizedError.message);
+    if (sanitizedError.suggestion) {
+        parts.push(`\nℹ️  ${sanitizedError.suggestion}`);
+    }
+    return parts.join(' ');
+}
+/**
+ * Create internal log message with full details (not sanitized)
+ *
+ * @param error - Original error
+ * @param context - Additional context
+ * @returns Detailed log message
+ */
+export function createInternalLogMessage(error, context) {
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    const parts = [
+        `Error: ${errorObj.message}`,
+    ];
+    if (errorObj.stack) {
+        parts.push(`Stack: ${sanitizeStackTrace(errorObj.stack)}`);
+    }
+    if (context) {
+        parts.push(`Context: ${JSON.stringify(context, null, 2)}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Safe error wrapper for user-facing operations
+ *
+ * @param operation - Async operation to execute
+ * @param errorHandler - Optional custom error handler
+ * @returns Result or sanitized error
+ *
+ * @example
+ * ```typescript
+ * const result = await safeExecute(
+ *   () => riskyOperation(),
+ *   (error) => console.error('Internal error:', error)
+ * );
+ *
+ * if (!result.success) {
+ *   console.log(formatUserError(result.error));
+ * }
+ * ```
+ */
+export async function safeExecute(operation, errorHandler) {
+    try {
+        const data = await operation();
+        return { success: true, data };
+    }
+    catch (error) {
+        const sanitized = sanitizeError(error);
+        // Log internal error details
+        if (errorHandler) {
+            errorHandler(sanitized.originalError, sanitized);
+        }
+        else {
+            console.error(createInternalLogMessage(error));
+        }
+        return { success: false, error: sanitized };
+    }
+}
+//# sourceMappingURL=error-sanitizer.js.map

package/dist/utils/error-sanitizer.js.map

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

package/dist/utils/errors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Typed Error Classes
+ * Provides consistent, categorized error handling across the application
+ */
+/**
+ * Base error class for AX CLI errors
+ */
+export declare class AxCliError extends Error {
+    readonly category: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, category: string, details?: unknown | undefined);
+}
+/**
+ * Configuration-related errors (YAML, settings, etc.)
+ */
+export declare class ConfigurationError extends AxCliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Validation errors (Zod, schema, input validation)
+ */
+export declare class ValidationError extends AxCliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * File system operation errors
+ */
+export declare class FileSystemError extends AxCliError {
+    readonly filePath?: string | undefined;
+    constructor(message: string, filePath?: string | undefined, details?: unknown);
+}
+/**
+ * Network/API errors
+ */
+export declare class NetworkError extends AxCliError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: unknown);
+}
+/**
+ * MCP (Model Context Protocol) errors
+ */
+export declare class MCPError extends AxCliError {
+    readonly serverName?: string | undefined;
+    constructor(message: string, serverName?: string | undefined, details?: unknown);
+}
+/**
+ * Tool execution errors
+ */
+export declare class ToolExecutionError extends AxCliError {
+    readonly toolName?: string | undefined;
+    constructor(message: string, toolName?: string | undefined, details?: unknown);
+}
+/**
+ * Authentication/Authorization errors
+ */
+export declare class AuthenticationError extends AxCliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Type guard to check if error is an AxCliError
+ */
+export declare function isAxCliError(error: unknown): error is AxCliError;
+/**
+ * Extract user-friendly error message from any error type
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Format error for logging with details
+ */
+export declare function formatErrorForLogging(error: unknown): string;
+/**
+ * Wrap any error in an appropriate AxCliError
+ */
+export declare function wrapError(error: unknown, category: string, context?: string): AxCliError;

package/dist/utils/errors.js

@@ -0,0 +1,139 @@
+/**
+ * Typed Error Classes
+ * Provides consistent, categorized error handling across the application
+ */
+/**
+ * Base error class for AX CLI errors
+ */
+export class AxCliError extends Error {
+    category;
+    details;
+    constructor(message, category, details) {
+        super(message);
+        this.category = category;
+        this.details = details;
+        this.name = 'AxCliError';
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * Configuration-related errors (YAML, settings, etc.)
+ */
+export class ConfigurationError extends AxCliError {
+    constructor(message, details) {
+        super(message, 'Configuration', details);
+        this.name = 'ConfigurationError';
+    }
+}
+/**
+ * Validation errors (Zod, schema, input validation)
+ */
+export class ValidationError extends AxCliError {
+    constructor(message, details) {
+        super(message, 'Validation', details);
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * File system operation errors
+ */
+export class FileSystemError extends AxCliError {
+    filePath;
+    constructor(message, filePath, details) {
+        super(message, 'FileSystem', details);
+        this.filePath = filePath;
+        this.name = 'FileSystemError';
+    }
+}
+/**
+ * Network/API errors
+ */
+export class NetworkError extends AxCliError {
+    statusCode;
+    constructor(message, statusCode, details) {
+        super(message, 'Network', details);
+        this.statusCode = statusCode;
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * MCP (Model Context Protocol) errors
+ */
+export class MCPError extends AxCliError {
+    serverName;
+    constructor(message, serverName, details) {
+        super(message, 'MCP', details);
+        this.serverName = serverName;
+        this.name = 'MCPError';
+    }
+}
+/**
+ * Tool execution errors
+ */
+export class ToolExecutionError extends AxCliError {
+    toolName;
+    constructor(message, toolName, details) {
+        super(message, 'ToolExecution', details);
+        this.toolName = toolName;
+        this.name = 'ToolExecutionError';
+    }
+}
+/**
+ * Authentication/Authorization errors
+ */
+export class AuthenticationError extends AxCliError {
+    constructor(message, details) {
+        super(message, 'Authentication', details);
+        this.name = 'AuthenticationError';
+    }
+}
+/**
+ * Type guard to check if error is an AxCliError
+ */
+export function isAxCliError(error) {
+    return error instanceof AxCliError;
+}
+/**
+ * Extract user-friendly error message from any error type
+ */
+export function getErrorMessage(error) {
+    if (error instanceof AxCliError) {
+        return error.message;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'An unknown error occurred';
+}
+/**
+ * Format error for logging with details
+ */
+export function formatErrorForLogging(error) {
+    if (error instanceof AxCliError) {
+        let message = `[${error.category}] ${error.message}`;
+        if (error.details) {
+            message += `\nDetails: ${JSON.stringify(error.details, null, 2)}`;
+        }
+        if (error.stack) {
+            message += `\nStack: ${error.stack}`;
+        }
+        return message;
+    }
+    if (error instanceof Error) {
+        return error.stack || error.message;
+    }
+    return String(error);
+}
+/**
+ * Wrap any error in an appropriate AxCliError
+ */
+export function wrapError(error, category, context) {
+    const message = context
+        ? `${context}: ${getErrorMessage(error)}`
+        : getErrorMessage(error);
+    return new AxCliError(message, category, error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/incremental-analyzer.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Incremental Analyzer
+ *
+ * Analyzes only changed files and their dependencies using git integration.
+ * Provides 10-50x speedup by avoiding analysis of unchanged files.
+ *
+ * Quick Win #2: Git-Based Incremental Analysis (Est. time: 1 hour)
+ * Impact: 10-50x reduction in files to analyze
+ */
+/**
+ * Configuration for incremental analysis
+ */
+export interface IncrementalConfig {
+    /** Base directory for git operations (default: cwd) */
+    baseDir?: string;
+    /** File patterns to include (default: all) */
+    include?: string[];
+    /** File patterns to exclude (default: none) */
+    exclude?: string[];
+    /** Compare against specific commit/branch (default: HEAD) */
+    compareWith?: string;
+    /** Include untracked files (default: true) */
+    includeUntracked?: boolean;
+    /** Build dependency graph (default: false, for future use) */
+    trackDependencies?: boolean;
+}
+/**
+ * Changed file info
+ */
+export interface ChangedFile {
+    /** File path relative to base directory */
+    path: string;
+    /** Type of change */
+    status: 'modified' | 'added' | 'deleted' | 'renamed' | 'untracked';
+    /** Previous path (for renamed files) */
+    oldPath?: string;
+}
+/**
+ * Result of incremental analysis
+ */
+export interface IncrementalResult {
+    /** Files that need analysis */
+    filesToAnalyze: string[];
+    /** Files that are cached */
+    cachedFiles: string[];
+    /** Changed files detected */
+    changedFiles: ChangedFile[];
+    /** Total files in project */
+    totalFiles: number;
+    /** Estimated speedup */
+    speedup: number;
+}
+/**
+ * Check if directory is a git repository
+ */
+export declare function isGitRepo(dir?: string): boolean;
+/**
+ * Get changed files from git
+ *
+ * @param config - Configuration options
+ * @returns Array of changed files
+ *
+ * @example
+ * ```typescript
+ * const changed = await getChangedFiles({
+ *   compareWith: 'main',
+ *   include: ['*.ts', '*.tsx'],
+ * });
+ *
+ * console.log(`${changed.length} files changed`);
+ * ```
+ */
+export declare function getChangedFiles(config?: IncrementalConfig): Promise<ChangedFile[]>;
+/**
+ * Get files to analyze incrementally
+ *
+ * Returns only files that need analysis based on git changes.
+ *
+ * @param allFiles - All files in project
+ * @param config - Configuration options
+ * @returns Incremental analysis result
+ *
+ * @example
+ * ```typescript
+ * const allFiles = await glob('src/** /*.ts');
+ * const result = await getFilesToAnalyze(allFiles);
+ *
+ * console.log(`Analyzing ${result.filesToAnalyze.length} of ${result.totalFiles} files`);
+ * console.log(`Speedup: ${result.speedup.toFixed(1)}x`);
+ * ```
+ */
+export declare function getFilesToAnalyze(allFiles: string[], config?: IncrementalConfig): Promise<IncrementalResult>;
+/**
+ * Get git repository info
+ *
+ * @param baseDir - Base directory (default: cwd)
+ * @returns Repository information
+ */
+export declare function getGitInfo(baseDir?: string): {
+    branch: string;
+    commit: string;
+    isDirty: boolean;
+    ahead: number;
+    behind: number;
+} | null;
+/**
+ * Simple dependency tracker (for future use)
+ *
+ * Parses import/require statements to build a dependency graph.
+ */
+export declare class DependencyTracker {
+    private graph;
+    private reverseGraph;
+    /**
+     * Add a file and its dependencies
+     */
+    addFile(filePath: string): Promise<void>;
+    /**
+     * Get files that depend on the given file
+     */
+    getDependents(filePath: string): string[];
+    /**
+     * Get all affected files (transitive dependencies)
+     */
+    getAffectedFiles(changedFiles: string[]): string[];
+    /**
+     * Parse import statements from file content
+     */
+    private parseImports;
+    /**
+     * Resolve import path to absolute path
+     */
+    private resolveImport;
+}