@hesed/mysql 0.1.0

package/dist/mysql/mysql-client.js

@@ -0,0 +1,131 @@
+import { readConfig } from '../config.js';
+import { MySQLUtil } from './mysql-utils.js';
+let mysqlUtil = null;
+let cachedConfig = null;
+let cachedConfigDir;
+/**
+ * Set the config directory for the singleton client
+ * @param dir - Oclif config directory path
+ */
+export function setConfigDir(dir) {
+    cachedConfigDir = dir;
+}
+/**
+ * Initialize (or return cached) MySQLUtil
+ */
+async function initMySQL() {
+    if (mysqlUtil)
+        return mysqlUtil;
+    if (!cachedConfigDir) {
+        throw new Error('MySQL client not initialized. Call setConfigDir() before running commands.');
+    }
+    const jsonConfig = await readConfig(cachedConfigDir, console.error);
+    if (!jsonConfig) {
+        throw new Error('Missing connection config. Run "mq mysql auth add" to create a config.');
+    }
+    cachedConfig = {
+        defaultFormat: 'table',
+        defaultProfile: jsonConfig.defaultProfile,
+        profiles: jsonConfig.profiles,
+        safety: {
+            blacklistedOperations: ['DROP DATABASE'],
+            defaultLimit: 100,
+            requireConfirmationFor: ['DELETE', 'UPDATE', 'DROP', 'TRUNCATE', 'ALTER'],
+        },
+    };
+    mysqlUtil = new MySQLUtil(cachedConfig);
+    return mysqlUtil;
+}
+/**
+ * Get the loaded MySQL config, initializing if needed
+ */
+export async function getMySQLConfig() {
+    if (!cachedConfig) {
+        await initMySQL();
+    }
+    return cachedConfig;
+}
+/**
+ * Execute SQL query
+ * @param query - SQL query to execute
+ * @param profile - Database profile name
+ * @param format - Output format
+ * @param skipConfirmation - Skip confirmation for destructive operations
+ */
+export async function executeQuery(query, profile, format = 'table', skipConfirmation = false) {
+    return (await initMySQL()).executeQuery(profile, query, format, skipConfirmation);
+}
+/**
+ * List all databases
+ * @param profile - Database profile name
+ */
+export async function listDatabases(profile) {
+    return (await initMySQL()).listDatabases(profile);
+}
+/**
+ * List all tables in current database
+ * @param profile - Database profile name
+ */
+export async function listTables(profile) {
+    return (await initMySQL()).listTables(profile);
+}
+/**
+ * Describe table structure
+ * @param profile - Database profile name
+ * @param table - Table name
+ * @param format - Output format
+ */
+export async function describeTable(profile, table, format = 'table') {
+    return (await initMySQL()).describeTable(profile, table, format);
+}
+/**
+ * Show table indexes
+ * @param profile - Database profile name
+ * @param table - Table name
+ * @param format - Output format
+ */
+export async function showIndexes(profile, table, format = 'table') {
+    return (await initMySQL()).showIndexes(profile, table, format);
+}
+/**
+ * Explain query execution plan
+ * @param profile - Database profile name
+ * @param query - SQL query to explain
+ * @param format - Output format
+ */
+export async function explainQuery(profile, query, format = 'table') {
+    return (await initMySQL()).explainQuery(profile, query, format);
+}
+/**
+ * Test a connection directly with profile options (without loading JSON config)
+ * @param profile - Database connection profile options
+ */
+export async function testDirectConnection(profile) {
+    const tempConfig = {
+        defaultFormat: 'table',
+        defaultProfile: '_auth',
+        profiles: { _auth: profile },
+        safety: {
+            blacklistedOperations: [],
+            defaultLimit: 100,
+            requireConfirmationFor: [],
+        },
+    };
+    const tempUtil = new MySQLUtil(tempConfig);
+    try {
+        return await tempUtil.testConnection('_auth');
+    }
+    finally {
+        await tempUtil.closeAll();
+    }
+}
+/**
+ * Close all connections
+ */
+export async function closeConnections() {
+    if (mysqlUtil) {
+        await mysqlUtil.closeAll();
+        mysqlUtil = null;
+        cachedConfig = null;
+    }
+}

package/dist/mysql/mysql-utils.d.ts

@@ -0,0 +1,68 @@
+import type { FieldPacket, RowDataPacket } from 'mysql2/promise';
+import type { MySQLConfig } from './config-loader.js';
+import type { ConnectionTestResult, DatabaseListResult, DatabaseUtil, ExplainResult, IndexResult, OutputFormat, QueryResult, TableListResult, TableStructureResult } from './database.js';
+/**
+ * MySQL Database Utility
+ * Provides core database operations with safety validation and formatting
+ */
+export declare class MySQLUtil implements DatabaseUtil {
+    private config;
+    private connectionPool;
+    constructor(config: MySQLConfig);
+    /**
+     * Close all connections
+     */
+    closeAll(): Promise<void>;
+    /**
+     * Describe table structure
+     */
+    describeTable(profileName: string, table: string, format?: 'json' | 'table' | 'toon'): Promise<TableStructureResult>;
+    /**
+     * Validate and execute a SQL query
+     */
+    executeQuery(profileName: string, query: string, format?: OutputFormat, skipConfirmation?: boolean): Promise<QueryResult>;
+    /**
+     * Explain query execution plan
+     */
+    explainQuery(profileName: string, query: string, format?: 'json' | 'table' | 'toon'): Promise<ExplainResult>;
+    /**
+     * Format query results as CSV
+     */
+    formatAsCsv(rows: RowDataPacket[], fields: FieldPacket[]): string;
+    /**
+     * Format query results as JSON
+     */
+    formatAsJson(rows: RowDataPacket[]): string;
+    /**
+     * Format query results as table
+     */
+    formatAsTable(rows: RowDataPacket[], fields: FieldPacket[]): string;
+    /**
+     * Format query results as TOON
+     */
+    formatAsToon(rows: RowDataPacket[]): string;
+    /**
+     * List all databases
+     */
+    listDatabases(profileName: string): Promise<DatabaseListResult>;
+    /**
+     * List all tables in current database
+     */
+    listTables(profileName: string): Promise<TableListResult>;
+    /**
+     * Show table indexes
+     */
+    showIndexes(profileName: string, table: string, format?: 'json' | 'table' | 'toon'): Promise<IndexResult>;
+    /**
+     * Test database connection
+     */
+    testConnection(profileName: string): Promise<ConnectionTestResult>;
+    /**
+     * Format rows for SELECT/SHOW/DESCRIBE/EXPLAIN query result
+     */
+    private formatSelectResult;
+    /**
+     * Get or create MySQL connection for a profile
+     */
+    private getConnection;
+}

package/dist/mysql/mysql-utils.js

@@ -0,0 +1,370 @@
+import { encode } from '@toon-format/toon';
+import mysql from 'mysql2/promise';
+import { getMySQLConnectionOptions } from './config-loader.js';
+import { analyzeQuery, applyDefaultLimit, checkBlacklist, getQueryType, requiresConfirmation } from './query-validator.js';
+/**
+ * MySQL Database Utility
+ * Provides core database operations with safety validation and formatting
+ */
+export class MySQLUtil {
+    config;
+    connectionPool;
+    constructor(config) {
+        this.config = config;
+        this.connectionPool = new Map();
+    }
+    /**
+     * Close all connections
+     */
+    async closeAll() {
+        await Promise.all([...this.connectionPool.values()].map((conn) => conn.end()));
+        this.connectionPool.clear();
+    }
+    /**
+     * Describe table structure
+     */
+    async describeTable(profileName, table, format = 'table') {
+        try {
+            const connection = await this.getConnection(profileName);
+            const [rows, fields] = await connection.query(`DESCRIBE ${table}`);
+            let result = '';
+            if (format === 'json') {
+                result += this.formatAsJson(rows);
+            }
+            else if (format === 'toon') {
+                result += this.formatAsToon(rows);
+            }
+            else {
+                result += this.formatAsTable(rows, fields);
+            }
+            return {
+                result,
+                structure: rows,
+                success: true,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                error: `ERROR: ${errorMessage}`,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Validate and execute a SQL query
+     */
+    async executeQuery(profileName, query, format = 'table', skipConfirmation = false) {
+        const blacklistCheck = checkBlacklist(query, this.config.safety.blacklistedOperations);
+        if (!blacklistCheck.allowed) {
+            return {
+                error: `${blacklistCheck.reason}\n\nThis operation is blocked by safety rules and cannot be executed.`,
+                success: false,
+            };
+        }
+        if (!skipConfirmation) {
+            const confirmationCheck = requiresConfirmation(query, this.config.safety.requireConfirmationFor);
+            if (confirmationCheck.required) {
+                return {
+                    message: `${confirmationCheck.message}\nQuery: ${query}`,
+                    requiresConfirmation: true,
+                    success: false,
+                };
+            }
+        }
+        const warnings = analyzeQuery(query);
+        let warningText = '';
+        if (warnings.length > 0) {
+            warningText =
+                'Query Analysis:\n' +
+                    warnings.map((w) => `  [${w.level.toUpperCase()}] ${w.message}\n  → ${w.suggestion}`).join('\n') +
+                    '\n\n';
+        }
+        let finalQuery = query;
+        const queryType = getQueryType(query);
+        if (queryType === 'SELECT') {
+            finalQuery = applyDefaultLimit(query, this.config.safety.defaultLimit);
+            if (finalQuery !== query) {
+                warningText += `Applied default LIMIT ${this.config.safety.defaultLimit}\n\n`;
+            }
+        }
+        try {
+            const connection = await this.getConnection(profileName);
+            const [rows, fields] = await connection.query(finalQuery);
+            let result = '';
+            if (queryType === 'SELECT' || queryType === 'SHOW' || queryType === 'DESCRIBE' || queryType === 'EXPLAIN') {
+                result += this.formatSelectResult(rows, fields, format);
+            }
+            else {
+                const okPacket = rows;
+                const affectedRows = okPacket.affectedRows ?? 0;
+                const insertId = okPacket.insertId ?? null;
+                result += `Query executed successfully.\n`;
+                result += `Affected rows: ${affectedRows}\n`;
+                if (insertId) {
+                    result += `Insert ID: ${insertId}\n`;
+                }
+            }
+            return {
+                result: warningText + result,
+                success: true,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                error: `ERROR: ${errorMessage}`,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Explain query execution plan
+     */
+    async explainQuery(profileName, query, format = 'table') {
+        try {
+            const connection = await this.getConnection(profileName);
+            const [rows, fields] = await connection.query(`EXPLAIN ${query}`);
+            let result = '';
+            if (format === 'json') {
+                result += this.formatAsJson(rows);
+            }
+            else if (format === 'toon') {
+                result += this.formatAsToon(rows);
+            }
+            else {
+                result += this.formatAsTable(rows, fields);
+            }
+            return {
+                plan: rows,
+                result,
+                success: true,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                error: `ERROR: ${errorMessage}`,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Format query results as CSV
+     */
+    formatAsCsv(rows, fields) {
+        if (!rows || rows.length === 0) {
+            return '';
+        }
+        const columnNames = fields.map((f) => f.name);
+        let csv = columnNames.join(',') + '\n';
+        for (const row of rows) {
+            const values = columnNames.map((name) => {
+                const value = row[name] ?? '';
+                const str = String(value);
+                if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+                    return '"' + str.replaceAll('"', '""') + '"';
+                }
+                return str;
+            });
+            csv += values.join(',') + '\n';
+        }
+        return csv;
+    }
+    /**
+     * Format query results as JSON
+     */
+    formatAsJson(rows) {
+        return JSON.stringify(rows, null, 2);
+    }
+    /**
+     * Format query results as table
+     */
+    formatAsTable(rows, fields) {
+        if (!rows || rows.length === 0) {
+            return 'No results';
+        }
+        const columnNames = fields.map((f) => f.name);
+        const columnWidths = columnNames.map((name) => {
+            const dataWidth = Math.max(...rows.map((row) => String(row[name] ?? '').length));
+            return Math.max(name.length, dataWidth, 3);
+        });
+        let table = '┌' + columnWidths.map((w) => '─'.repeat(w + 2)).join('┬') + '┐\n';
+        table += '│ ' + columnNames.map((name, i) => name.padEnd(columnWidths[i])).join(' │ ') + ' │\n';
+        table += '├' + columnWidths.map((w) => '─'.repeat(w + 2)).join('┼') + '┤\n';
+        for (const row of rows) {
+            table +=
+                '│ ' +
+                    columnNames
+                        .map((name, i) => {
+                        const value = row[name] ?? 'NULL';
+                        return String(value).padEnd(columnWidths[i]);
+                    })
+                        .join(' │ ') +
+                    ' │\n';
+        }
+        table += '└' + columnWidths.map((w) => '─'.repeat(w + 2)).join('┴') + '┘';
+        return table;
+    }
+    /**
+     * Format query results as TOON
+     */
+    formatAsToon(rows) {
+        if (!rows || rows.length === 0) {
+            return '';
+        }
+        const serializedRows = rows.map((row) => {
+            const serialized = {};
+            for (const [key, value] of Object.entries(row)) {
+                if (value instanceof Date) {
+                    serialized[key] = Number.isNaN(value.getTime()) ? null : value.toISOString();
+                }
+                else if (Buffer.isBuffer(value)) {
+                    serialized[key] = value.toString('base64');
+                }
+                else {
+                    serialized[key] = value;
+                }
+            }
+            return serialized;
+        });
+        return encode(serializedRows);
+    }
+    /**
+     * List all databases
+     */
+    async listDatabases(profileName) {
+        try {
+            const connection = await this.getConnection(profileName);
+            const [rows] = await connection.query('SHOW DATABASES');
+            const databases = rows.map((row) => row.Database);
+            return {
+                databases,
+                result: `Databases:\n${databases.map((db) => `  • ${db}`).join('\n')}`,
+                success: true,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                error: `ERROR: ${errorMessage}`,
+                success: false,
+            };
+        }
+    }
+    /**
+     * List all tables in current database
+     */
+    async listTables(profileName) {
+        try {
+            const connection = await this.getConnection(profileName);
+            const [rows] = await connection.query('SHOW TABLES');
+            const rowsArray = rows;
+            const tableKey = Object.keys(rowsArray[0])[0];
+            const tables = rowsArray.map((row) => row[tableKey]);
+            return {
+                result: `Tables in database:\n${tables.map((table) => `  • ${table}`).join('\n')}`,
+                success: true,
+                tables,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                error: `ERROR: ${errorMessage}`,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Show table indexes
+     */
+    async showIndexes(profileName, table, format = 'table') {
+        try {
+            const connection = await this.getConnection(profileName);
+            const [rows, fields] = await connection.query(`SHOW INDEXES FROM ${table}`);
+            let result = '';
+            if (format === 'json') {
+                result += this.formatAsJson(rows);
+            }
+            else if (format === 'toon') {
+                result += this.formatAsToon(rows);
+            }
+            else {
+                result += this.formatAsTable(rows, fields);
+            }
+            return {
+                indexes: rows,
+                result,
+                success: true,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                error: `ERROR: ${errorMessage}`,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Test database connection
+     */
+    async testConnection(profileName) {
+        try {
+            const connection = await this.getConnection(profileName);
+            const [rows] = await connection.query('SELECT VERSION() as version, DATABASE() as current_database');
+            const info = rows[0];
+            return {
+                database: info.current_database,
+                result: `Connection successful!\n\nProfile: ${profileName}\nMySQL Version: ${info.version}\nCurrent Database: ${info.current_database}`,
+                success: true,
+                version: info.version,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                error: `ERROR: ${errorMessage}`,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Format rows for SELECT/SHOW/DESCRIBE/EXPLAIN query result
+     */
+    formatSelectResult(rows, fields, format) {
+        const rowCount = Array.isArray(rows) ? rows.length : 0;
+        let result = `Query executed successfully. Rows returned: ${rowCount}\n\n`;
+        switch (format) {
+            case 'csv': {
+                result += this.formatAsCsv(rows, fields);
+                break;
+            }
+            case 'json': {
+                result += this.formatAsJson(rows);
+                break;
+            }
+            case 'toon': {
+                result += this.formatAsToon(rows);
+                break;
+            }
+            default: {
+                result += this.formatAsTable(rows, fields);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get or create MySQL connection for a profile
+     */
+    async getConnection(profileName) {
+        if (this.connectionPool.has(profileName)) {
+            return this.connectionPool.get(profileName);
+        }
+        const options = getMySQLConnectionOptions(this.config, profileName);
+        const connection = await mysql.createConnection(options);
+        this.connectionPool.set(profileName, connection);
+        return connection;
+    }
+}

package/dist/mysql/query-validator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Query Validation and Safety Module
+ * Provides SQL query analysis and safety checks
+ */
+interface BlacklistCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+interface ConfirmationCheckResult {
+    message?: string;
+    required: boolean;
+}
+interface QueryWarning {
+    level: 'info' | 'warning';
+    message: string;
+    suggestion: string;
+}
+/**
+ * Check if query contains blacklisted operations
+ */
+export declare function checkBlacklist(query: string, blacklistedOperations: string[]): BlacklistCheckResult;
+/**
+ * Check if query requires user confirmation
+ */
+export declare function requiresConfirmation(query: string, confirmationOperations: string[]): ConfirmationCheckResult;
+/**
+ * Get query type (SELECT, INSERT, UPDATE, etc.)
+ */
+export declare function getQueryType(query: string): string;
+/**
+ * Analyze query for potential issues and provide warnings
+ */
+export declare function analyzeQuery(query: string): QueryWarning[];
+/**
+ * Apply default LIMIT to SELECT queries if not present
+ */
+export declare function applyDefaultLimit(query: string, defaultLimit: number): string;
+export {};