@hesed/psql 0.1.0

package/dist/commands/psql/auth/update.js

@@ -0,0 +1,74 @@
+import { confirm, input } from '@inquirer/prompts';
+import { Command, Flags } from '@oclif/core';
+import { action } from '@oclif/core/ux';
+import { default as fs } from 'fs-extra';
+import { default as path } from 'node:path';
+import { testDirectConnection } from '../../../psql/index.js';
+export default class AuthUpdate extends Command {
+    static args = {};
+    static description = 'Update an existing PostgreSQL connection profile';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --ssl',
+        '<%= config.bin %> <%= command.id %> --profile staging',
+    ];
+    static flags = {
+        database: Flags.string({ char: 'd', description: 'Database name', required: !process.stdout.isTTY }),
+        host: Flags.string({ description: 'PostgreSQL host', required: !process.stdout.isTTY }),
+        password: Flags.string({ char: 'p', description: 'Password', required: !process.stdout.isTTY }),
+        port: Flags.integer({ char: 'P', description: 'PostgreSQL port', required: !process.stdout.isTTY }),
+        profile: Flags.string({ description: 'Profile name to update', required: false }),
+        ssl: Flags.boolean({ allowNo: true, default: false, description: 'Use SSL', required: false }),
+        user: Flags.string({ char: 'u', description: 'Username', required: !process.stdout.isTTY }),
+    };
+    async run() {
+        const { flags } = await this.parse(AuthUpdate);
+        const configPath = path.join(this.config.configDir, 'pg-config.json');
+        let config;
+        try {
+            config = await fs.readJSON(configPath);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg.toLowerCase().includes('no such file or directory')) {
+                this.log('Run auth:add instead');
+            }
+            else {
+                this.log(msg);
+            }
+            return;
+        }
+        const profileName = flags.profile ?? config.defaultProfile;
+        const existingProfile = config.profiles[profileName];
+        if (!existingProfile) {
+            this.error(`Profile "${profileName}" not found. Available: ${Object.keys(config.profiles).join(', ')}`);
+        }
+        const host = flags.host ??
+            (await input({ default: existingProfile.host, message: 'PostgreSQL host:', prefill: 'tab', required: true }));
+        const port = flags.port ??
+            Number(await input({ default: String(existingProfile.port), message: 'Port:', prefill: 'tab', required: true }));
+        const user = flags.user ?? (await input({ default: existingProfile.user, message: 'Username:', prefill: 'tab', required: true }));
+        const password = flags.password ??
+            (await input({ default: existingProfile.password, message: 'Password:', prefill: 'tab', required: true }));
+        const database = flags.database ??
+            (await input({ default: existingProfile.database, message: 'Database:', prefill: 'tab', required: true }));
+        const answer = await confirm({ message: `Override profile "${profileName}"?` });
+        if (!answer) {
+            return;
+        }
+        config.profiles[profileName] = { database, host, password, port, ssl: flags.ssl, user };
+        await fs.writeJSON(configPath, config, { mode: 0o600 });
+        action.start('Testing connection');
+        const updatedConfig = await fs.readJSON(configPath);
+        const result = await testDirectConnection(updatedConfig.profiles[profileName]);
+        if (result.success) {
+            action.stop('✓ successful');
+            this.log(`Profile "${profileName}" updated successfully`);
+        }
+        else {
+            action.stop('✗ failed');
+            this.error('Connection failed. Please check your configuration.');
+        }
+        return result;
+    }
+}

package/dist/commands/psql/databases.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class PostgresDatabases extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/psql/databases.js

@@ -0,0 +1,31 @@
+import { Command, Flags } from '@oclif/core';
+import { closeConnections, getPgConfig, listDatabases, setConfigDir } from '../../psql/index.js';
+export default class PostgresDatabases extends Command {
+    static description = 'List all databases accessible on the PostgreSQL server';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --profile staging',
+    ];
+    static flags = {
+        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+    };
+    async run() {
+        const { flags } = await this.parse(PostgresDatabases);
+        setConfigDir(this.config.configDir);
+        let profile;
+        try {
+            profile = flags.profile ?? (await getPgConfig()).defaultProfile;
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        const result = await listDatabases(profile);
+        await closeConnections();
+        if (result.success) {
+            this.logJson(result.databases);
+        }
+        else {
+            this.error(result.error ?? 'Failed to list databases');
+        }
+    }
+}

package/dist/commands/psql/describe-table.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class PostgresDescribeTable extends Command {
+    static args: {
+        table: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/psql/describe-table.js

@@ -0,0 +1,39 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { closeConnections, describeTable, getPgConfig, setConfigDir } from '../../psql/index.js';
+export default class PostgresDescribeTable extends Command {
+    static args = {
+        table: Args.string({ description: 'Table name to describe', required: true }),
+    };
+    static description = 'Describe the structure of a PostgreSQL table';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> users',
+        '<%= config.bin %> <%= command.id %> orders --format json --profile prod',
+    ];
+    static flags = {
+        format: Flags.string({
+            default: 'table',
+            description: 'Output format',
+            options: ['table', 'json', 'toon'],
+        }),
+        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(PostgresDescribeTable);
+        setConfigDir(this.config.configDir);
+        let profile;
+        try {
+            profile = flags.profile ?? (await getPgConfig()).defaultProfile;
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        const result = await describeTable(profile, args.table, flags.format);
+        await closeConnections();
+        if (result.success) {
+            this.log(result.result ?? '');
+        }
+        else {
+            this.error(result.error ?? 'Failed to describe table');
+        }
+    }
+}

package/dist/commands/psql/explain-query.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class PostgresExplain extends Command {
+    static args: {
+        query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/psql/explain-query.js

@@ -0,0 +1,39 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { closeConnections, explainQuery, getPgConfig, setConfigDir } from '../../psql/index.js';
+export default class PostgresExplain extends Command {
+    static args = {
+        query: Args.string({ description: 'SQL query to explain', required: true }),
+    };
+    static description = 'Show the execution plan for a PostgreSQL query';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> "SELECT * FROM users WHERE id = 1"',
+        '<%= config.bin %> <%= command.id %> "SELECT * FROM orders JOIN users ON orders.user_id = users.id" --format json',
+    ];
+    static flags = {
+        format: Flags.string({
+            default: 'table',
+            description: 'Output format',
+            options: ['table', 'json', 'toon'],
+        }),
+        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(PostgresExplain);
+        setConfigDir(this.config.configDir);
+        let profile;
+        try {
+            profile = flags.profile ?? (await getPgConfig()).defaultProfile;
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        const result = await explainQuery(profile, args.query, flags.format);
+        await closeConnections();
+        if (result.success) {
+            this.log(result.result ?? '');
+        }
+        else {
+            this.error(result.error ?? 'Failed to explain query');
+        }
+    }
+}

package/dist/commands/psql/indexes.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class PostgresIndexes extends Command {
+    static args: {
+        table: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/psql/indexes.js

@@ -0,0 +1,39 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { closeConnections, getPgConfig, setConfigDir, showIndexes } from '../../psql/index.js';
+export default class PostgresIndexes extends Command {
+    static args = {
+        table: Args.string({ description: 'Table name to show indexes for', required: true }),
+    };
+    static description = 'Show indexes for a PostgreSQL table';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> users',
+        '<%= config.bin %> <%= command.id %> orders --format json --profile prod',
+    ];
+    static flags = {
+        format: Flags.string({
+            default: 'table',
+            description: 'Output format',
+            options: ['table', 'json', 'toon'],
+        }),
+        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(PostgresIndexes);
+        setConfigDir(this.config.configDir);
+        let profile;
+        try {
+            profile = flags.profile ?? (await getPgConfig()).defaultProfile;
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        const result = await showIndexes(profile, args.table, flags.format);
+        await closeConnections();
+        if (result.success) {
+            this.log(result.result ?? '');
+        }
+        else {
+            this.error(result.error ?? 'Failed to show indexes');
+        }
+    }
+}

package/dist/commands/psql/query.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class PostgresQuery extends Command {
+    static args: {
+        query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'skip-confirmation': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/psql/query.js

@@ -0,0 +1,47 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { closeConnections, executeQuery, getPgConfig, setConfigDir } from '../../psql/index.js';
+export default class PostgresQuery extends Command {
+    static args = {
+        query: Args.string({ description: 'SQL query to execute', required: true }),
+    };
+    static description = 'Execute a SQL query against a PostgreSQL database';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> "SELECT * FROM users LIMIT 10"',
+        '<%= config.bin %> <%= command.id %> "UPDATE users SET email = \'user@email.com\' WHERE id = 999" --format json',
+        '<%= config.bin %> <%= command.id %> "DELETE FROM sessions" --profile prod --skip-confirmation',
+    ];
+    static flags = {
+        format: Flags.string({
+            default: 'table',
+            description: 'Output format',
+            options: ['table', 'json', 'csv', 'toon'],
+        }),
+        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+        'skip-confirmation': Flags.boolean({
+            default: false,
+            description: 'Skip confirmation prompt for destructive operations',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(PostgresQuery);
+        setConfigDir(this.config.configDir);
+        let profile;
+        try {
+            profile = flags.profile ?? (await getPgConfig()).defaultProfile;
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        const result = await executeQuery(args.query, profile, flags.format, flags['skip-confirmation']);
+        await closeConnections();
+        if (result.success) {
+            this.log(result.result ?? '');
+        }
+        else if (result.requiresConfirmation) {
+            this.log(`${result.message ?? 'Destructive operation requires confirmation.'}\nRe-run with --skip-confirmation to proceed.`);
+        }
+        else {
+            this.error(result.error ?? 'Query failed');
+        }
+    }
+}

package/dist/commands/psql/tables.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class PostgresTables extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/psql/tables.js

@@ -0,0 +1,31 @@
+import { Command, Flags } from '@oclif/core';
+import { closeConnections, getPgConfig, listTables, setConfigDir } from '../../psql/index.js';
+export default class PostgresTables extends Command {
+    static description = 'List all tables in the current PostgreSQL database';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --profile local',
+    ];
+    static flags = {
+        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+    };
+    async run() {
+        const { flags } = await this.parse(PostgresTables);
+        setConfigDir(this.config.configDir);
+        let profile;
+        try {
+            profile = flags.profile ?? (await getPgConfig()).defaultProfile;
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        const result = await listTables(profile);
+        await closeConnections();
+        if (result.success) {
+            this.logJson(result.tables);
+        }
+        else {
+            this.error(result.error ?? 'Failed to list tables');
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export interface DatabaseProfile {
+    database: string;
+    host: string;
+    password: string;
+    port: number;
+    ssl?: boolean;
+    user: string;
+}
+export interface PgJsonConfig {
+    defaultProfile: string;
+    profiles: Record<string, DatabaseProfile>;
+}
+export declare function readConfig(configDir: string, log: (message: string) => void): Promise<PgJsonConfig | undefined>;

package/dist/config.js

@@ -0,0 +1,18 @@
+import { default as fs } from 'fs-extra';
+import { default as path } from 'node:path';
+export async function readConfig(configDir, log) {
+    const configPath = path.join(configDir, 'pg-config.json');
+    try {
+        return await fs.readJSON(configPath);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.toLowerCase().includes('no such file or directory')) {
+            log('Missing connection config');
+        }
+        else {
+            log(msg);
+        }
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/psql/config-loader.d.ts

@@ -0,0 +1,28 @@
+import type { ClientConfig } from 'pg';
+import type { DatabaseProfile } from '../config.js';
+/**
+ * Safety configuration for query execution
+ */
+interface SafetyConfig {
+    blacklistedOperations: string[];
+    defaultLimit: number;
+    requireConfirmationFor: string[];
+}
+/**
+ * Main configuration structure
+ */
+export interface PgConfig {
+    defaultFormat: 'csv' | 'json' | 'table' | 'toon';
+    defaultProfile: string;
+    profiles: Record<string, DatabaseProfile>;
+    safety: SafetyConfig;
+}
+/**
+ * Get PostgreSQL connection options for a specific profile
+ *
+ * @param config - Configuration object
+ * @param profileName - Profile name
+ * @returns pg ClientConfig options
+ */
+export declare function getPgConnectionOptions(config: PgConfig, profileName: string): ClientConfig;
+export {};

package/dist/psql/config-loader.js

@@ -0,0 +1,26 @@
+/**
+ * Get PostgreSQL connection options for a specific profile
+ *
+ * @param config - Configuration object
+ * @param profileName - Profile name
+ * @returns pg ClientConfig options
+ */
+export function getPgConnectionOptions(config, profileName) {
+    const profile = config.profiles[profileName];
+    if (!profile) {
+        const availableProfiles = Object.keys(config.profiles).join(', ');
+        throw new Error(`Profile "${profileName}" not found. Available profiles: ${availableProfiles}`);
+    }
+    const options = {
+        connectionTimeoutMillis: 10_000,
+        database: profile.database,
+        host: profile.host,
+        password: profile.password,
+        port: profile.port,
+        user: profile.user,
+    };
+    if (profile.ssl) {
+        options.ssl = {};
+    }
+    return options;
+}

package/dist/psql/database.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Database abstraction interface
+ * Defines the contract for the PostgreSQL utility implementation
+ */
+/**
+ * Query execution result for SELECT/EXPLAIN queries
+ */
+export interface QueryResult {
+    error?: string;
+    message?: string;
+    requiresConfirmation?: boolean;
+    result?: string;
+    success: boolean;
+}
+/**
+ * Database list result
+ */
+export interface DatabaseListResult {
+    databases?: string[];
+    error?: string;
+    result?: string;
+    success: boolean;
+}
+/**
+ * Table list result
+ */
+export interface TableListResult {
+    error?: string;
+    result?: string;
+    success: boolean;
+    tables?: string[];
+}
+/**
+ * Table structure result
+ */
+export interface TableStructureResult {
+    error?: string;
+    result?: string;
+    structure?: Record<string, unknown>[];
+    success: boolean;
+}
+/**
+ * Index information result
+ */
+export interface IndexResult {
+    error?: string;
+    indexes?: Record<string, unknown>[];
+    result?: string;
+    success: boolean;
+}
+/**
+ * Query plan result
+ */
+export interface ExplainResult {
+    error?: string;
+    plan?: Record<string, unknown>[];
+    result?: string;
+    success: boolean;
+}
+/**
+ * Connection test result
+ */
+export interface ConnectionTestResult {
+    database?: string;
+    error?: string;
+    result?: string;
+    success: boolean;
+    version?: string;
+}
+/**
+ * Output format type
+ */
+export type OutputFormat = 'csv' | 'json' | 'table' | 'toon';
+/**
+ * Database utility interface
+ */
+export interface DatabaseUtil {
+    closeAll(): Promise<void>;
+    describeTable(profileName: string, table: string, format?: OutputFormat): Promise<TableStructureResult>;
+    executeQuery(profileName: string, query: string, format?: OutputFormat, skipConfirmation?: boolean): Promise<QueryResult>;
+    explainQuery(profileName: string, query: string, format?: OutputFormat): Promise<ExplainResult>;
+    listDatabases(profileName: string): Promise<DatabaseListResult>;
+    listTables(profileName: string): Promise<TableListResult>;
+    showIndexes(profileName: string, table: string, format?: OutputFormat): Promise<IndexResult>;
+}

package/dist/psql/database.js

@@ -0,0 +1,5 @@
+/**
+ * Database abstraction interface
+ * Defines the contract for the PostgreSQL utility implementation
+ */
+export {};

package/dist/psql/index.d.ts

@@ -0,0 +1,3 @@
+export type { PgJsonConfig } from '../config.js';
+export type { ConnectionTestResult } from './database.js';
+export { closeConnections, describeTable, executeQuery, explainQuery, getPgConfig, listDatabases, listTables, setConfigDir, showIndexes, testDirectConnection, } from './postgres-client.js';

package/dist/psql/index.js

@@ -0,0 +1 @@
+export { closeConnections, describeTable, executeQuery, explainQuery, getPgConfig, listDatabases, listTables, setConfigDir, showIndexes, testDirectConnection, } from './postgres-client.js';

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

@@ -0,0 +1,60 @@
+import type { DatabaseProfile } from '../config.js';
+import type { PgConfig } from './config-loader.js';
+import type { ConnectionTestResult, DatabaseListResult, ExplainResult, IndexResult, OutputFormat, QueryResult, TableListResult, TableStructureResult } from './database.js';
+/**
+ * Set the config directory for the singleton client
+ * @param dir - Oclif config directory path
+ */
+export declare function setConfigDir(dir: string): void;
+/**
+ * Get the loaded PostgreSQL config, initializing if needed
+ */
+export declare function getPgConfig(): Promise<PgConfig>;
+/**
+ * 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 declare function executeQuery(query: string, profile: string, format?: OutputFormat, skipConfirmation?: boolean): Promise<QueryResult>;
+/**
+ * List all databases
+ * @param profile - Database profile name
+ */
+export declare function listDatabases(profile: string): Promise<DatabaseListResult>;
+/**
+ * List all tables in current database
+ * @param profile - Database profile name
+ */
+export declare function listTables(profile: string): Promise<TableListResult>;
+/**
+ * Describe table structure
+ * @param profile - Database profile name
+ * @param table - Table name
+ * @param format - Output format
+ */
+export declare function describeTable(profile: string, table: string, format?: 'json' | 'table' | 'toon'): Promise<TableStructureResult>;
+/**
+ * Show table indexes
+ * @param profile - Database profile name
+ * @param table - Table name
+ * @param format - Output format
+ */
+export declare function showIndexes(profile: string, table: string, format?: 'json' | 'table' | 'toon'): Promise<IndexResult>;
+/**
+ * Explain query execution plan
+ * @param profile - Database profile name
+ * @param query - SQL query to explain
+ * @param format - Output format
+ */
+export declare function explainQuery(profile: string, query: string, format?: 'json' | 'table' | 'toon'): Promise<ExplainResult>;
+/**
+ * Test a connection directly with profile options (without loading JSON config)
+ * @param profile - Database connection profile options
+ */
+export declare function testDirectConnection(profile: DatabaseProfile): Promise<ConnectionTestResult>;
+/**
+ * Close all connections
+ */
+export declare function closeConnections(): Promise<void>;