@hesed/psql 0.1.0

package/dist/psql/postgres-client.js

@@ -0,0 +1,131 @@
+import { readConfig } from '../config.js';
+import { PostgreSQLUtil } from './postgres-utils.js';
+let pgUtil = 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) PostgreSQLUtil
+ */
+async function initPg() {
+    if (pgUtil)
+        return pgUtil;
+    if (!cachedConfigDir) {
+        throw new Error('PostgreSQL client not initialized. Call setConfigDir() before running commands.');
+    }
+    const jsonConfig = await readConfig(cachedConfigDir, console.error);
+    if (!jsonConfig) {
+        throw new Error('Missing connection config. Run "pg psql 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'],
+        },
+    };
+    pgUtil = new PostgreSQLUtil(cachedConfig);
+    return pgUtil;
+}
+/**
+ * Get the loaded PostgreSQL config, initializing if needed
+ */
+export async function getPgConfig() {
+    if (!cachedConfig) {
+        await initPg();
+    }
+    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 initPg()).executeQuery(profile, query, format, skipConfirmation);
+}
+/**
+ * List all databases
+ * @param profile - Database profile name
+ */
+export async function listDatabases(profile) {
+    return (await initPg()).listDatabases(profile);
+}
+/**
+ * List all tables in current database
+ * @param profile - Database profile name
+ */
+export async function listTables(profile) {
+    return (await initPg()).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 initPg()).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 initPg()).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 initPg()).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 PostgreSQLUtil(tempConfig);
+    try {
+        return await tempUtil.testConnection('_auth');
+    }
+    finally {
+        await tempUtil.closeAll();
+    }
+}
+/**
+ * Close all connections
+ */
+export async function closeConnections() {
+    if (pgUtil) {
+        await pgUtil.closeAll();
+        pgUtil = null;
+        cachedConfig = null;
+    }
+}

package/dist/psql/postgres-utils.d.ts

@@ -0,0 +1,72 @@
+import type { PgConfig } from './config-loader.js';
+import type { ConnectionTestResult, DatabaseListResult, DatabaseUtil, ExplainResult, IndexResult, OutputFormat, QueryResult, TableListResult, TableStructureResult } from './database.js';
+type PgRow = Record<string, unknown>;
+type PgField = {
+    name: string;
+};
+/**
+ * PostgreSQL Database Utility
+ * Provides core database operations with safety validation and formatting
+ */
+export declare class PostgreSQLUtil implements DatabaseUtil {
+    private config;
+    private connectionPool;
+    constructor(config: PgConfig);
+    /**
+     * 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: PgRow[], fields: PgField[]): string;
+    /**
+     * Format query results as JSON
+     */
+    formatAsJson(rows: PgRow[]): string;
+    /**
+     * Format query results as table
+     */
+    formatAsTable(rows: PgRow[], fields: PgField[]): string;
+    /**
+     * Format query results as TOON
+     */
+    formatAsToon(rows: PgRow[]): 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/EXPLAIN query result
+     */
+    private formatSelectResult;
+    /**
+     * Get or create PostgreSQL client for a profile
+     */
+    private getConnection;
+}
+export {};

package/dist/psql/postgres-utils.js

@@ -0,0 +1,364 @@
+import { encode } from '@toon-format/toon';
+import pg from 'pg';
+import { getPgConnectionOptions } from './config-loader.js';
+import { analyzeQuery, applyDefaultLimit, checkBlacklist, getQueryType, requiresConfirmation } from './query-validator.js';
+/**
+ * PostgreSQL Database Utility
+ * Provides core database operations with safety validation and formatting
+ */
+export class PostgreSQLUtil {
+    config;
+    connectionPool;
+    constructor(config) {
+        this.config = config;
+        this.connectionPool = new Map();
+    }
+    /**
+     * Close all connections
+     */
+    async closeAll() {
+        await Promise.all([...this.connectionPool.values()].map((c) => c.end()));
+        this.connectionPool.clear();
+    }
+    /**
+     * Describe table structure
+     */
+    async describeTable(profileName, table, format = 'table') {
+        try {
+            const client = await this.getConnection(profileName);
+            const result = await client.query(`SELECT column_name, data_type, character_maximum_length, is_nullable, column_default FROM information_schema.columns WHERE table_name = '${table}' AND table_schema = 'public' ORDER BY ordinal_position`);
+            let output = '';
+            if (format === 'json') {
+                output += this.formatAsJson(result.rows);
+            }
+            else if (format === 'toon') {
+                output += this.formatAsToon(result.rows);
+            }
+            else {
+                output += this.formatAsTable(result.rows, result.fields);
+            }
+            return {
+                result: output,
+                structure: result.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 client = await this.getConnection(profileName);
+            const result = await client.query(finalQuery);
+            let output = '';
+            if (result.rows.length > 0 || result.command === 'SELECT' || result.command === 'EXPLAIN') {
+                output += this.formatSelectResult(result.rows, result.fields, format);
+            }
+            else {
+                const affectedRows = result.rowCount ?? 0;
+                output += `Query executed successfully.\n`;
+                output += `Affected rows: ${affectedRows}\n`;
+            }
+            return {
+                result: warningText + output,
+                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 client = await this.getConnection(profileName);
+            const result = await client.query(`EXPLAIN ${query}`);
+            let output = '';
+            if (format === 'json') {
+                output += this.formatAsJson(result.rows);
+            }
+            else if (format === 'toon') {
+                output += this.formatAsToon(result.rows);
+            }
+            else {
+                output += this.formatAsTable(result.rows, result.fields);
+            }
+            return {
+                plan: result.rows,
+                result: output,
+                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 client = await this.getConnection(profileName);
+            const result = await client.query('SELECT datname FROM pg_database WHERE datistemplate = false ORDER BY datname');
+            const databases = result.rows.map((row) => row.datname);
+            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 client = await this.getConnection(profileName);
+            const result = await client.query("SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename");
+            const tables = result.rows.map((row) => row.tablename);
+            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 client = await this.getConnection(profileName);
+            const result = await client.query(`SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table}' AND schemaname = 'public'`);
+            let output = '';
+            if (format === 'json') {
+                output += this.formatAsJson(result.rows);
+            }
+            else if (format === 'toon') {
+                output += this.formatAsToon(result.rows);
+            }
+            else {
+                output += this.formatAsTable(result.rows, result.fields);
+            }
+            return {
+                indexes: result.rows,
+                result: output,
+                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 client = await this.getConnection(profileName);
+            const result = await client.query('SELECT version() as version, current_database() as current_database');
+            const info = result.rows[0];
+            return {
+                database: info.current_database,
+                result: `Connection successful!\n\nProfile: ${profileName}\nPostgreSQL 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/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 PostgreSQL client for a profile
+     */
+    async getConnection(profileName) {
+        if (this.connectionPool.has(profileName)) {
+            return this.connectionPool.get(profileName);
+        }
+        const options = getPgConnectionOptions(this.config, profileName);
+        const client = new pg.Client(options);
+        await client.connect();
+        this.connectionPool.set(profileName, client);
+        return client;
+    }
+}

package/dist/psql/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 {};

package/dist/psql/query-validator.js

@@ -0,0 +1,91 @@
+/**
+ * Query Validation and Safety Module
+ * Provides SQL query analysis and safety checks
+ */
+/**
+ * Check if query contains blacklisted operations
+ */
+export function checkBlacklist(query, blacklistedOperations) {
+    const normalizedQuery = query.trim().toUpperCase();
+    for (const operation of blacklistedOperations) {
+        const normalizedOp = operation.toUpperCase();
+        if (normalizedQuery.includes(normalizedOp)) {
+            return {
+                allowed: false,
+                reason: `Operation "${operation}" is blacklisted and not allowed`,
+            };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Check if query requires user confirmation
+ */
+export function requiresConfirmation(query, confirmationOperations) {
+    const normalizedQuery = query.trim().toUpperCase();
+    for (const operation of confirmationOperations) {
+        const normalizedOp = operation.toUpperCase();
+        if (normalizedQuery.startsWith(normalizedOp) || normalizedQuery.includes(` ${normalizedOp} `)) {
+            return {
+                message: `This query contains a destructive operation: ${operation}`,
+                required: true,
+            };
+        }
+    }
+    return { required: false };
+}
+/**
+ * Get query type (SELECT, INSERT, UPDATE, etc.)
+ */
+export function getQueryType(query) {
+    const normalizedQuery = query.trim().toUpperCase();
+    const firstWord = normalizedQuery.split(/\s+/)[0];
+    const knownTypes = ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'DROP', 'CREATE', 'ALTER', 'TRUNCATE', 'EXPLAIN'];
+    if (knownTypes.includes(firstWord)) {
+        return firstWord;
+    }
+    return 'UNKNOWN';
+}
+/**
+ * Analyze query for potential issues and provide warnings
+ */
+export function analyzeQuery(query) {
+    const warnings = [];
+    const normalizedQuery = query.trim().toUpperCase();
+    // Check for missing WHERE clause in UPDATE/DELETE
+    if ((normalizedQuery.startsWith('UPDATE') || normalizedQuery.startsWith('DELETE')) &&
+        !normalizedQuery.includes('WHERE')) {
+        warnings.push({
+            level: 'warning',
+            message: 'Missing WHERE clause in UPDATE/DELETE query',
+            suggestion: 'This will affect all rows in the table. Add a WHERE clause to limit scope.',
+        });
+    }
+    // Check for SELECT * (potential performance issue)
+    if (normalizedQuery.includes('SELECT *')) {
+        warnings.push({
+            level: 'info',
+            message: 'Using SELECT * may impact performance',
+            suggestion: 'Consider selecting only the columns you need.',
+        });
+    }
+    // Check for missing LIMIT in SELECT
+    if (normalizedQuery.startsWith('SELECT') && !normalizedQuery.includes('LIMIT')) {
+        warnings.push({
+            level: 'info',
+            message: 'SELECT query without LIMIT',
+            suggestion: 'Consider adding a LIMIT clause to prevent large result sets.',
+        });
+    }
+    return warnings;
+}
+/**
+ * Apply default LIMIT to SELECT queries if not present
+ */
+export function applyDefaultLimit(query, defaultLimit) {
+    const normalizedQuery = query.trim().toUpperCase();
+    if (normalizedQuery.startsWith('SELECT') && !normalizedQuery.includes('LIMIT')) {
+        return `${query.trim()} LIMIT ${defaultLimit}`;
+    }
+    return query;
+}