sqlew 3.5.3 → 3.6.1

package/dist/utils/debug-logger.js

@@ -0,0 +1,267 @@
+/**
+ * Debug Logger for MCP Shared Context Server
+ *
+ * Enables debug logging when specified via CLI arg, environment variable, or config file.
+ * Priority: CLI arg > Environment variable > Config file
+ *
+ * Usage:
+ *   node dist/index.js --debug-log=/path/to/debug.log
+ *   SQLEW_DEBUG=/path/to/debug.log node dist/index.js
+ *   OR set debug.log_path in .sqlew/config.toml
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+let debugEnabled = false;
+let debugStream = null;
+let currentLogPath = null;
+let currentLogLevel = 'INFO';
+// Log level hierarchy (higher number = more verbose)
+const LOG_LEVELS = {
+    'ERROR': 1,
+    'WARN': 2,
+    'INFO': 3,
+    'DEBUG': 4
+};
+/**
+ * Check if a log level should be written
+ * @param level - Level to check
+ * @returns true if should log
+ */
+function shouldLog(level) {
+    const levelValue = LOG_LEVELS[level.toUpperCase()] || 0;
+    const currentValue = LOG_LEVELS[currentLogLevel];
+    return levelValue <= currentValue;
+}
+/**
+ * Initialize debug logger
+ * @param debugLogPath - Log path (already resolved with priority: CLI > env > config)
+ * @param logLevel - Log level (case-insensitive: "error", "warn", "info", "debug")
+ */
+export function initDebugLogger(debugLogPath, logLevel) {
+    if (!debugLogPath) {
+        return;
+    }
+    currentLogPath = debugLogPath;
+    // Set log level (case-insensitive, default to INFO)
+    if (logLevel) {
+        const upperLevel = logLevel.toUpperCase();
+        if (LOG_LEVELS[upperLevel]) {
+            currentLogLevel = upperLevel;
+        }
+    }
+    try {
+        // Ensure directory exists
+        const logDir = path.dirname(debugLogPath);
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        // Create write stream (append mode)
+        debugStream = fs.createWriteStream(debugLogPath, { flags: 'a' });
+        debugEnabled = true;
+        // Detect source (for logging purposes)
+        const cliArg = process.argv.find(arg => arg.startsWith('--debug-log'));
+        const envVar = process.env.SQLEW_DEBUG;
+        const source = cliArg ? 'CLI Argument' : envVar ? 'Environment Variable' : 'Config File';
+        const sourceDetail = cliArg ? '--debug-log' : envVar ? 'SQLEW_DEBUG' : 'debug.log_path';
+        debugLog('INFO', '='.repeat(80));
+        debugLog('INFO', `MCP Shared Context Server Debug Log Started`);
+        debugLog('INFO', `Timestamp: ${new Date().toISOString()}`);
+        debugLog('INFO', `Process ID: ${process.pid}`);
+        debugLog('INFO', `Debug Log Path: ${debugLogPath}`);
+        debugLog('INFO', `Log Level: ${currentLogLevel}`);
+        debugLog('INFO', `Source: ${source} (${sourceDetail})`);
+        debugLog('INFO', '='.repeat(80));
+    }
+    catch (error) {
+        console.error(`Failed to initialize debug logger: ${error}`);
+        debugEnabled = false;
+    }
+}
+/**
+ * Write debug log entry
+ * @param level - Log level (INFO, WARN, ERROR, DEBUG)
+ * @param message - Log message
+ * @param data - Optional data to log
+ */
+export function debugLog(level, message, data) {
+    if (!debugEnabled || !debugStream) {
+        return;
+    }
+    // Check log level filtering
+    if (!shouldLog(level)) {
+        return;
+    }
+    const timestamp = new Date().toISOString();
+    let logEntry = `[${timestamp}] [${level}] ${message}`;
+    try {
+        if (data !== undefined) {
+            const dataStr = typeof data === 'string'
+                ? data
+                : JSON.stringify(data);
+            logEntry += ` | Data: ${dataStr}`;
+        }
+        debugStream.write(logEntry + '\n');
+    }
+    catch (error) {
+        console.error(`Failed to write debug log: ${error}`);
+    }
+}
+/**
+ * Log MCP tool call
+ */
+export function debugLogToolCall(toolName, action, params) {
+    debugLog('DEBUG', `Tool Call: ${toolName}.${action}`, { params });
+}
+/**
+ * Log MCP tool response
+ */
+export function debugLogToolResponse(toolName, action, success, result, error) {
+    debugLog(success ? 'DEBUG' : 'ERROR', `Tool Response: ${toolName}.${action} ${success ? 'SUCCESS' : 'FAILED'}`, success ? result : error);
+}
+/**
+ * Log error with stack trace
+ */
+export function debugLogError(context, error, additionalContext) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    debugLog('ERROR', `${context}: ${errorMessage}`, {
+        stack,
+        ...additionalContext
+    });
+}
+/**
+ * Close debug logger
+ */
+export function closeDebugLogger() {
+    if (debugStream) {
+        debugLog('INFO', 'MCP Shared Context Server Debug Log Ended');
+        debugLog('INFO', '_'.repeat(80));
+        debugStream.end();
+        debugStream = null;
+        debugEnabled = false;
+    }
+}
+/**
+ * Check if debug logging is enabled
+ */
+export function isDebugEnabled() {
+    return debugEnabled;
+}
+// ============================================================================
+// Enhanced Debug Logging for Crash Investigation
+// ============================================================================
+/**
+ * Log database query execution with detailed information
+ */
+export function debugLogQuery(context, sql, params, duration) {
+    if (!debugEnabled)
+        return;
+    const logData = {
+        sql: sql.replace(/\s+/g, ' ').trim(),
+        params: params || null
+    };
+    if (duration !== undefined) {
+        logData.duration_ms = duration;
+    }
+    debugLog('DEBUG', `DB Query [${context}]`, logData);
+}
+/**
+ * Log connection pool state
+ */
+export function debugLogPoolState(context, poolState) {
+    if (!debugEnabled)
+        return;
+    debugLog('DEBUG', `Connection Pool State [${context}]`, poolState);
+}
+/**
+ * Log transaction boundaries
+ */
+export function debugLogTransaction(action, context, transactionId) {
+    if (!debugEnabled)
+        return;
+    debugLog('DEBUG', `Transaction ${action} [${context}]`, { transaction_id: transactionId });
+}
+/**
+ * Log parameter validation
+ */
+export function debugLogValidation(context, paramName, value, valid, errorMsg) {
+    if (!debugEnabled)
+        return;
+    debugLog(valid ? 'DEBUG' : 'WARN', `Parameter Validation [${context}]`, {
+        parameter: paramName,
+        value: typeof value === 'object' ? JSON.stringify(value) : value,
+        valid,
+        error: errorMsg || null
+    });
+}
+/**
+ * Log schema operation (insert, update, select)
+ */
+export function debugLogSchemaOperation(operation, table, columns, whereClause, values) {
+    if (!debugEnabled)
+        return;
+    debugLog('DEBUG', `Schema Operation: ${operation} ${table}`, {
+        columns: columns || null,
+        where: whereClause || null,
+        values: values || null
+    });
+}
+/**
+ * Log JSON parsing/serialization
+ */
+export function debugLogJSON(context, operation, input, success, error) {
+    if (!debugEnabled)
+        return;
+    debugLog(success ? 'DEBUG' : 'ERROR', `JSON ${operation} [${context}]`, {
+        input: typeof input === 'string' ? input : JSON.stringify(input),
+        success,
+        error: error || null
+    });
+}
+/**
+ * Log function entry with parameters
+ */
+export function debugLogFunctionEntry(functionName, params) {
+    if (!debugEnabled)
+        return;
+    debugLog('DEBUG', `→ Function Entry: ${functionName}`, { params });
+}
+/**
+ * Log function exit with result
+ */
+export function debugLogFunctionExit(functionName, success, result, error) {
+    if (!debugEnabled)
+        return;
+    debugLog(success ? 'DEBUG' : 'ERROR', `← Function Exit: ${functionName} ${success ? 'SUCCESS' : 'FAILED'}`, success ? { result } : { error: error instanceof Error ? error.message : String(error) });
+}
+/**
+ * Log connection acquisition
+ */
+export function debugLogConnectionAcquire(context, waitTime) {
+    if (!debugEnabled)
+        return;
+    debugLog('DEBUG', `Connection Acquired [${context}]`, { wait_time_ms: waitTime || 0 });
+}
+/**
+ * Log connection release
+ */
+export function debugLogConnectionRelease(context, duration) {
+    if (!debugEnabled)
+        return;
+    debugLog('DEBUG', `Connection Released [${context}]`, { duration_ms: duration || 0 });
+}
+/**
+ * Log critical error with full context
+ */
+export function debugLogCriticalError(context, error, additionalContext) {
+    if (!debugEnabled)
+        return;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    debugLog('ERROR', `💥 CRITICAL ERROR [${context}]`, {
+        error: errorMessage,
+        stack,
+        ...additionalContext
+    });
+}
+//# sourceMappingURL=debug-logger.js.map

package/dist/utils/debug-logger.js.map

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

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Centralized error handling module for MCP Sqlew server
+ * Provides consistent error logging, reporting, and recovery
+ */
+/**
+ * Handle tool execution errors
+ * Logs the error with context and returns formatted error response
+ */
+export declare function handleToolError(toolName: string, action: string, error: any, params?: any): {
+    message: string;
+    stack?: string;
+};
+/**
+ * Handle initialization errors
+ * Logs the error and returns formatted error message
+ */
+export declare function handleInitializationError(error: any): string;
+/**
+ * Setup global error handlers for uncaught exceptions and unhandled rejections
+ * Server continues running to maintain availability
+ */
+export declare function setupGlobalErrorHandlers(onCleanup?: () => void): void;
+/**
+ * Handle validation errors
+ * Returns user-friendly error message
+ */
+export declare function handleValidationError(toolName: string, action: string, validationMessage: string): string;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/utils/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmBH;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,GAAG,EACV,MAAM,CAAC,EAAE,GAAG,GACX;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAyBrC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAiB5D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,CAAC,EAAE,MAAM,IAAI,GACrB,IAAI,CAsDN;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,GACxB,MAAM,CAMR"}

package/dist/utils/error-handler.js

@@ -0,0 +1,121 @@
+/**
+ * Centralized error handling module for MCP Sqlew server
+ * Provides consistent error logging, reporting, and recovery
+ */
+import { debugLog, debugLogError } from './debug-logger.js';
+/**
+ * Format error details for logging and reporting
+ */
+function formatErrorDetails(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    const errorType = error?.constructor?.name || 'Unknown';
+    return { message, stack, errorType };
+}
+/**
+ * Handle tool execution errors
+ * Logs the error with context and returns formatted error response
+ */
+export function handleToolError(toolName, action, error, params) {
+    const { message, stack, errorType } = formatErrorDetails(error);
+    // Enhanced debug logging with full error details
+    debugLogError(`Tool ${toolName}.${action}`, error, {
+        tool: toolName,
+        action: action,
+        params: params,
+        errorType: errorType,
+        stack: stack
+    });
+    // Log to stderr for immediate visibility
+    console.error(`\n❌ ERROR in ${toolName}.${action}:`);
+    console.error(`   Message: ${message}`);
+    if (stack) {
+        console.error(`   Stack trace:`);
+        console.error(stack.split('\n').map(line => `     ${line}`).join('\n'));
+    }
+    if (params) {
+        console.error(`   Params: ${JSON.stringify(params, null, 2)}`);
+    }
+    console.error('');
+    return { message, stack };
+}
+/**
+ * Handle initialization errors
+ * Logs the error and returns formatted error message
+ */
+export function handleInitializationError(error) {
+    const { message, stack, errorType } = formatErrorDetails(error);
+    debugLogError('INITIALIZATION_ERROR', error, {
+        errorType: errorType,
+        stack: stack
+    });
+    console.error('\n❌ INITIALIZATION ERROR:');
+    console.error(`   Message: ${message}`);
+    if (stack) {
+        console.error(`   Stack trace:`);
+        console.error(stack.split('\n').map(line => `     ${line}`).join('\n'));
+    }
+    console.error('');
+    return message;
+}
+/**
+ * Setup global error handlers for uncaught exceptions and unhandled rejections
+ * Server continues running to maintain availability
+ */
+export function setupGlobalErrorHandlers(onCleanup) {
+    // Handle uncaught exceptions
+    process.on('uncaughtException', (error) => {
+        const { message, stack, errorType } = formatErrorDetails(error);
+        console.error('\n❌ UNCAUGHT EXCEPTION (server continuing):');
+        console.error(`   Message: ${message}`);
+        console.error(`   Stack trace:`);
+        console.error(stack?.split('\n').map(line => `     ${line}`).join('\n'));
+        debugLogError('UNCAUGHT_EXCEPTION', error, {
+            errorType: errorType,
+            stack: stack
+        });
+        console.error('   ⚠️  Server continuing despite error\n');
+    });
+    // Handle unhandled promise rejections
+    process.on('unhandledRejection', (reason, promise) => {
+        const { message, stack, errorType } = formatErrorDetails(reason);
+        console.error('\n❌ UNHANDLED PROMISE REJECTION (server continuing):');
+        console.error(`   Reason: ${message}`);
+        if (stack) {
+            console.error(`   Stack trace:`);
+            console.error(stack.split('\n').map(line => `     ${line}`).join('\n'));
+        }
+        debugLogError('UNHANDLED_REJECTION', reason, {
+            errorType: errorType,
+            stack: stack,
+            promise: String(promise)
+        });
+        console.error('   ⚠️  Server continuing despite error\n');
+    });
+    // Handle graceful shutdown
+    process.on('SIGINT', async () => {
+        console.error('\n✓ Shutting down MCP server...');
+        if (onCleanup) {
+            onCleanup();
+        }
+        process.exit(0);
+    });
+    process.on('SIGTERM', async () => {
+        console.error('\n✓ Shutting down MCP server...');
+        if (onCleanup) {
+            onCleanup();
+        }
+        process.exit(0);
+    });
+}
+/**
+ * Handle validation errors
+ * Returns user-friendly error message
+ */
+export function handleValidationError(toolName, action, validationMessage) {
+    debugLog('WARN', `Validation error in ${toolName}.${action}`, {
+        validation: validationMessage
+    });
+    return validationMessage;
+}
+//# sourceMappingURL=error-handler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;GAEG;AACH,SAAS,kBAAkB,CAAC,KAAU;IAKpC,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/D,MAAM,SAAS,GAAG,KAAK,EAAE,WAAW,EAAE,IAAI,IAAI,SAAS,CAAC;IAExD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,MAAc,EACd,KAAU,EACV,MAAY;IAEZ,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAEhE,iDAAiD;IACjD,aAAa,CAAC,QAAQ,QAAQ,IAAI,MAAM,EAAE,EAAE,KAAK,EAAE;QACjD,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,MAAM;QACd,SAAS,EAAE,SAAS;QACpB,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IAEH,yCAAyC;IACzC,OAAO,CAAC,KAAK,CAAC,gBAAgB,QAAQ,IAAI,MAAM,GAAG,CAAC,CAAC;IACrD,OAAO,CAAC,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;IACxC,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACjC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAElB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAU;IAClD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAEhE,aAAa,CAAC,sBAAsB,EAAE,KAAK,EAAE;QAC3C,SAAS,EAAE,SAAS;QACpB,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC3C,OAAO,CAAC,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;IACxC,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACjC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAElB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAsB;IAEtB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAY,EAAE,EAAE;QAC/C,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAEhE,OAAO,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAC7D,OAAO,CAAC,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAC;QACxC,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACjC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAEzE,aAAa,CAAC,oBAAoB,EAAE,KAAK,EAAE;YACzC,SAAS,EAAE,SAAS;YACpB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QAEH,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,sCAAsC;IACtC,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAW,EAAE,OAAqB,EAAE,EAAE;QACtE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAEjE,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;QACtE,OAAO,CAAC,KAAK,CAAC,cAAc,OAAO,EAAE,CAAC,CAAC;QACvC,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1E,CAAC;QAED,aAAa,CAAC,qBAAqB,EAAE,MAAM,EAAE;YAC3C,SAAS,EAAE,SAAS;YACpB,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC;SACzB,CAAC,CAAC;QAEH,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACjD,IAAI,SAAS,EAAE,CAAC;YACd,SAAS,EAAE,CAAC;QACd,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAC/B,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACjD,IAAI,SAAS,EAAE,CAAC;YACd,SAAS,EAAE,CAAC;QACd,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,MAAc,EACd,iBAAyB;IAEzB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,QAAQ,IAAI,MAAM,EAAE,EAAE;QAC5D,UAAU,EAAE,iBAAiB;KAC9B,CAAC,CAAC;IAEH,OAAO,iBAAiB,CAAC;AAC3B,CAAC"}

package/dist/utils/help-tracking.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Help Action Usage Tracking
+ *
+ * Lightweight logging system to track help/example action invocations
+ * for understanding usage patterns and optimizing documentation.
+ *
+ * Data collected:
+ * - tool_name: Which MCP tool invoked help/example
+ * - action_name: "help" or "example"
+ * - timestamp: When the action was invoked
+ * - token_count: Estimated tokens in request + response
+ *
+ * Storage: Temporary log file in .sqlew/tmp/help-usage.log
+ * Format: JSON lines (one JSON object per line for easy parsing)
+ * Retention: Manual cleanup after 1-2 week analysis period
+ */
+/**
+ * Help action invocation record
+ */
+export interface HelpUsageRecord {
+    tool_name: string;
+    action_name: 'help' | 'example' | 'use_case';
+    timestamp: string;
+    token_count: number;
+    context?: string;
+}
+/**
+ * Log a help action invocation
+ * Appends JSON line to log file for analysis
+ *
+ * @param record - Help usage record to log
+ */
+export declare function logHelpUsage(record: HelpUsageRecord): void;
+/**
+ * Estimate token count for help/example action
+ * Rough estimation based on response length
+ *
+ * @param toolName - Name of the MCP tool
+ * @param actionName - "help" or "example"
+ * @param responseLength - Length of response text
+ * @returns Estimated token count (request + response)
+ */
+export declare function estimateHelpTokens(toolName: string, actionName: 'help' | 'example' | 'use_case', responseLength: number): number;
+/**
+ * Track help action and return the help content
+ * Convenience wrapper that logs and returns content
+ *
+ * @param toolName - Name of the MCP tool
+ * @param actionName - "help" or "example"
+ * @param content - Help content to return
+ * @param context - Optional context about what triggered help
+ * @returns The help content (pass-through)
+ */
+export declare function trackAndReturnHelp(toolName: string, actionName: 'help' | 'example' | 'use_case', content: string, context?: string): string;
+//# sourceMappingURL=help-tracking.d.ts.map

package/dist/utils/help-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-tracking.d.ts","sourceRoot":"","sources":["../../src/utils/help-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAW1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,EAC3C,cAAc,EAAE,MAAM,GACrB,MAAM,CAQR;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,EAC3C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAYR"}

package/dist/utils/help-tracking.js

@@ -0,0 +1,88 @@
+/**
+ * Help Action Usage Tracking
+ *
+ * Lightweight logging system to track help/example action invocations
+ * for understanding usage patterns and optimizing documentation.
+ *
+ * Data collected:
+ * - tool_name: Which MCP tool invoked help/example
+ * - action_name: "help" or "example"
+ * - timestamp: When the action was invoked
+ * - token_count: Estimated tokens in request + response
+ *
+ * Storage: Temporary log file in .sqlew/tmp/help-usage.log
+ * Format: JSON lines (one JSON object per line for easy parsing)
+ * Retention: Manual cleanup after 1-2 week analysis period
+ */
+import { appendFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+/**
+ * Log file configuration
+ */
+const LOG_DIR = resolve(process.cwd(), '.sqlew', 'tmp');
+const LOG_FILE = resolve(LOG_DIR, 'help-usage.log');
+/**
+ * Initialize logging directory
+ * Creates .sqlew/tmp/ if it doesn't exist
+ */
+function ensureLogDirectory() {
+    if (!existsSync(LOG_DIR)) {
+        mkdirSync(LOG_DIR, { recursive: true });
+    }
+}
+/**
+ * Log a help action invocation
+ * Appends JSON line to log file for analysis
+ *
+ * @param record - Help usage record to log
+ */
+export function logHelpUsage(record) {
+    try {
+        ensureLogDirectory();
+        // Append as JSON line (newline-delimited JSON)
+        const jsonLine = JSON.stringify(record) + '\n';
+        appendFileSync(LOG_FILE, jsonLine, 'utf8');
+    }
+    catch (error) {
+        // Silent failure - don't break tool execution if logging fails
+        console.error('[Help Tracking] Failed to log usage:', error);
+    }
+}
+/**
+ * Estimate token count for help/example action
+ * Rough estimation based on response length
+ *
+ * @param toolName - Name of the MCP tool
+ * @param actionName - "help" or "example"
+ * @param responseLength - Length of response text
+ * @returns Estimated token count (request + response)
+ */
+export function estimateHelpTokens(toolName, actionName, responseLength) {
+    // Request tokens: tool name + action parameter (~50 tokens)
+    const requestTokens = 50;
+    // Response tokens: approximate 4 chars per token
+    const responseTokens = Math.ceil(responseLength / 4);
+    return requestTokens + responseTokens;
+}
+/**
+ * Track help action and return the help content
+ * Convenience wrapper that logs and returns content
+ *
+ * @param toolName - Name of the MCP tool
+ * @param actionName - "help" or "example"
+ * @param content - Help content to return
+ * @param context - Optional context about what triggered help
+ * @returns The help content (pass-through)
+ */
+export function trackAndReturnHelp(toolName, actionName, content, context) {
+    const tokenCount = estimateHelpTokens(toolName, actionName, content.length);
+    logHelpUsage({
+        tool_name: toolName,
+        action_name: actionName,
+        timestamp: new Date().toISOString(),
+        token_count: tokenCount,
+        context
+    });
+    return content;
+}
+//# sourceMappingURL=help-tracking.js.map

package/dist/utils/help-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-tracking.js","sourceRoot":"","sources":["../../src/utils/help-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAa/B;;GAEG;AACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;AAEpD;;;GAGG;AACH,SAAS,kBAAkB;IACzB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB;IAClD,IAAI,CAAC;QACH,kBAAkB,EAAE,CAAC;QAErB,+CAA+C;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;QAC/C,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+DAA+D;QAC/D,OAAO,CAAC,KAAK,CAAC,sCAAsC,EAAE,KAAK,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,UAA2C,EAC3C,cAAsB;IAEtB,4DAA4D;IAC5D,MAAM,aAAa,GAAG,EAAE,CAAC;IAEzB,iDAAiD;IACjD,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;IAErD,OAAO,aAAa,GAAG,cAAc,CAAC;AACxC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,UAA2C,EAC3C,OAAe,EACf,OAAgB;IAEhB,MAAM,UAAU,GAAG,kBAAkB,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5E,YAAY,CAAC;QACX,SAAS,EAAE,QAAQ;QACnB,WAAW,EAAE,UAAU;QACvB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,WAAW,EAAE,UAAU;QACvB,OAAO;KACR,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/param-parser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Parameter parsing utilities for MCP tool parameters
+ * Handles JSON array strings from MCP SDK
+ */
+/**
+ * Parse a parameter that could be a string array or a JSON-encoded string array
+ * MCP SDK sometimes sends arrays as JSON strings: "[\"tag1\", \"tag2\"]"
+ *
+ * @param param - The parameter to parse (array or JSON string)
+ * @returns Parsed string array
+ *
+ * @example
+ * parseStringArray(['tag1', 'tag2']) // returns ['tag1', 'tag2']
+ * parseStringArray('["tag1", "tag2"]') // returns ['tag1', 'tag2']
+ * parseStringArray('single-tag') // returns ['single-tag']
+ */
+export declare function parseStringArray(param: string | string[] | undefined | null): string[];
+/**
+ * Parse optional string array parameter
+ * Returns undefined if param is null/undefined/empty
+ */
+export declare function parseOptionalStringArray(param: string | string[] | undefined | null): string[] | undefined;
+//# sourceMappingURL=param-parser.d.ts.map

package/dist/utils/param-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-parser.d.ts","sourceRoot":"","sources":["../../src/utils/param-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,CA4BtF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,GAAG,SAAS,CAG1G"}