@heroku/heroku-cli-util 10.0.0-beta.2 → 10.1.0

package/dist/utils/pg/psql.js

@@ -3,155 +3,41 @@ import { spawn, } from 'node:child_process';
 import { EventEmitter, once } from 'node:events';
 import { Stream } from 'node:stream';
 import { finished } from 'node:stream/promises';
-import { getConfigs, sshTunnel } from './bastion.js';
+import { getPsqlConfigs, sshTunnel } from './bastion.js';
 const pgDebug = debug('pg');
-export function consumeStream(inputStream) {
-    let result = '';
-    const throughStream = new Stream.PassThrough();
-    // eslint-disable-next-line no-async-promise-executor
-    const promise = new Promise(async (resolve, reject) => {
-        try {
-            await finished(throughStream);
-            resolve(result);
-        }
-        catch (error) {
-            reject(error);
-        }
-    });
-    // eslint-disable-next-line no-return-assign
-    throughStream.on('data', chunk => result += chunk.toString());
-    inputStream.pipe(throughStream);
-    return promise;
-}
-export async function exec(db, query, cmdArgs = []) {
-    const configs = getConfigs(db);
-    const options = psqlQueryOptions(query, configs.dbEnv, cmdArgs);
-    return runWithTunnel(db, configs.dbTunnelConfig, options);
-}
-export function psqlQueryOptions(query, dbEnv, cmdArgs = []) {
-    pgDebug('Running query: %s', query.trim());
-    const psqlArgs = ['-c', query, '--set', 'sslmode=require', ...cmdArgs];
-    const childProcessOptions = {
-        stdio: ['ignore', 'pipe', 'inherit'],
-    };
-    return {
-        childProcessOptions,
-        dbEnv,
-        psqlArgs,
-    };
-}
-export function execPSQL({ childProcessOptions, dbEnv, psqlArgs }) {
-    const options = {
-        env: dbEnv,
-        ...childProcessOptions,
-    };
-    pgDebug('opening psql process');
-    const psql = spawn('psql', psqlArgs, options);
-    psql.once('spawn', () => pgDebug('psql process spawned'));
-    return psql;
-}
-// According to node.js docs, sending a kill to a process won't cause an error
-// but could have unintended consequences if the PID gets reassigned:
-// https://nodejs.org/docs/latest-v14.x/api/child_process.html#child_process_subprocess_kill_signal
-// To be on the safe side, check if the process was already killed before sending the signal
-function kill(childProcess, signal) {
-    if (!childProcess.killed) {
-        pgDebug('killing psql child process');
-        childProcess.kill(signal);
-    }
-}
-export async function runWithTunnel(db, tunnelConfig, options) {
-    const tunnel = await Tunnel.connect(db, tunnelConfig);
-    pgDebug('after create tunnel');
-    const psql = execPSQL(options);
-    // interactive opens with stdio: 'inherit'
-    // which gives the child process the same stdin,stdout,stderr of the node process (global `process`)
-    // https://nodejs.org/api/child_process.html#child_process_options_stdio
-    // psql.stdout will be null in this case
-    // return a string for consistency but ideally we should return the child process from this function
-    // and let the caller decide what to do with stdin/stdout/stderr
-    const stdoutPromise = psql.stdout ? consumeStream(psql.stdout) : Promise.resolve('');
-    const cleanupSignalTraps = trapAndForwardSignalsToChildProcess(psql);
-    try {
-        pgDebug('waiting for psql or tunnel to exit');
-        // wait for either psql or tunnel to exit;
-        // the important bit is that we ensure both processes are
-        // always cleaned up in the `finally` block below
-        await Promise.race([
-            waitForPSQLExit(psql),
-            tunnel.waitForClose(),
-        ]);
-    }
-    catch (error) {
-        pgDebug('wait for psql or tunnel error', error);
-        throw error;
-    }
-    finally {
-        pgDebug('begin tunnel cleanup');
-        cleanupSignalTraps();
-        tunnel.close();
-        kill(psql, 'SIGKILL');
-        pgDebug('end tunnel cleanup');
-    }
-    return stdoutPromise;
-}
-// trap SIGINT so that ctrl+c can be used by psql without killing the
-// parent node process.
-// you can use ctrl+c in psql to kill running queries
-// while keeping the psql process open.
-// This code is to stop the parent node process (heroku CLI)
-// from exiting. If the parent Heroku CLI node process exits, then psql will exit as it
-// is a child process of the Heroku CLI node process.
-export const trapAndForwardSignalsToChildProcess = (childProcess) => {
-    const signalsToTrap = ['SIGINT'];
-    const signalTraps = signalsToTrap.map(signal => {
-        process.removeAllListeners(signal);
-        const listener = () => kill(childProcess, signal);
-        process.on(signal, listener);
-        return [signal, listener];
-    });
-    // restores the built-in node ctrl+c and other handlers
-    return () => {
-        for (const [signal, listener] of signalTraps) {
-            process.removeListener(signal, listener);
-        }
-    };
-};
-export async function waitForPSQLExit(psql) {
-    let errorToThrow = null;
-    try {
-        const [exitCode] = await once(psql, 'close');
-        pgDebug(`psql exited with code ${exitCode}`);
-        if (exitCode > 0) {
-            errorToThrow = new Error(`psql exited with code ${exitCode}`);
-        }
-    }
-    catch (error) {
-        pgDebug('psql process error', error);
-        const { code } = error;
-        if (code === 'ENOENT') {
-            errorToThrow = new Error('The local psql command could not be located. For help installing psql, see https://devcenter.heroku.com/articles/heroku-postgresql#local-setup');
-        }
-    }
-    if (errorToThrow) {
-        throw errorToThrow;
-    }
-}
-// a small wrapper around tunnel-ssh
-// so that other code doesn't have to worry about
-// whether there is or is not a tunnel
+/**
+ * A small wrapper around tunnel-ssh so that other code doesn't have to worry about whether there is or is not a tunnel.
+ */
 export class Tunnel {
     bastionTunnel;
     events;
+    /**
+     * Creates a new Tunnel instance.
+     *
+     * @param bastionTunnel - The SSH tunnel server or void if no tunnel is needed
+     */
     constructor(bastionTunnel) {
         this.bastionTunnel = bastionTunnel;
         // eslint-disable-next-line unicorn/prefer-event-target
         this.events = new EventEmitter();
     }
-    static async connect(db, tunnelConfig) {
-        const tunnel = await sshTunnel(db, tunnelConfig);
+    /**
+     * Creates and connects to an SSH tunnel.
+     *
+     * @param connectionDetails - The database connection details with attachment information
+     * @param tunnelConfig - The tunnel configuration object
+     * @param tunnelFn - The function to create the SSH tunnel (default: sshTunnel)
+     * @returns Promise that resolves to a new Tunnel instance
+     */
+    static async connect(connectionDetails, tunnelConfig, tunnelFn) {
+        const tunnel = await tunnelFn(connectionDetails, tunnelConfig);
         return new Tunnel(tunnel);
     }
+    /**
+     * Closes the tunnel if it exists, or emits a fake close event if no tunnel is needed.
+     *
+     * @returns void
+     */
     close() {
         if (this.bastionTunnel) {
             pgDebug('close tunnel');
@@ -162,6 +48,12 @@ export class Tunnel {
             this.events.emit('close', 0);
         }
     }
+    /**
+     * Waits for the tunnel to close.
+     *
+     * @returns Promise that resolves when the tunnel closes
+     * @throws Error if the secure tunnel fails
+     */
     async waitForClose() {
         if (this.bastionTunnel) {
             try {
@@ -175,8 +67,203 @@ export class Tunnel {
             }
         }
         else {
-            pgDebug('no bastion required; waiting for fake close event');
+            pgDebug('no tunnel required; waiting for fake close event');
             await once(this.events, 'close');
         }
     }
 }
+export default class PsqlService {
+    connectionDetails;
+    getPsqlConfigsFn;
+    spawnFn;
+    tunnelFn;
+    constructor(connectionDetails, getPsqlConfigsFn = getPsqlConfigs, spawnFn = spawn, tunnelFn = sshTunnel) {
+        this.connectionDetails = connectionDetails;
+        this.getPsqlConfigsFn = getPsqlConfigsFn;
+        this.spawnFn = spawnFn;
+        this.tunnelFn = tunnelFn;
+    }
+    /**
+     * Executes a PostgreSQL query using the instance's database connection details.
+     * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
+     * and then calls the `runWithTunnel` function to execute the query.
+     *
+     * @param query - The SQL query to execute
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Promise that resolves to the query result as a string
+     */
+    async execQuery(query, psqlCmdArgs = []) {
+        const configs = this.getPsqlConfigsFn(this.connectionDetails);
+        const options = this.psqlQueryOptions(query, configs.dbEnv, psqlCmdArgs);
+        return this.runWithTunnel(configs.dbTunnelConfig, options);
+    }
+    /**
+     * Consumes a stream and returns its content as a string.
+     *
+     * @param inputStream - The input stream to consume
+     * @returns Promise that resolves to the stream content as a string
+     */
+    consumeStream(inputStream) {
+        let result = '';
+        const throughStream = new Stream.PassThrough();
+        // eslint-disable-next-line no-async-promise-executor
+        const promise = new Promise(async (resolve, reject) => {
+            try {
+                await finished(throughStream);
+                resolve(result);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        // eslint-disable-next-line no-return-assign
+        throughStream.on('data', chunk => result += chunk.toString());
+        inputStream.pipe(throughStream);
+        return promise;
+    }
+    /**
+     * Kills a child process if it hasn't been killed already.
+     * According to node.js docs, sending a kill to a process won't cause an error
+     * but could have unintended consequences if the PID gets reassigned.
+     * To be on the safe side, check if the process was already killed before sending the signal.
+     *
+     * @param childProcess - The child process to kill
+     * @param signal - The signal to send to the process
+     * @returns void
+     */
+    kill(childProcess, signal) {
+        if (!childProcess.killed) {
+            pgDebug('killing psql child process');
+            childProcess.kill(signal);
+        }
+    }
+    /**
+     * Creates the options for spawning the psql process.
+     *
+     * @param query - The SQL query to execute
+     * @param dbEnv - The database environment variables
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Object containing child process options, database environment, and psql arguments
+     */
+    psqlQueryOptions(query, dbEnv, psqlCmdArgs = []) {
+        pgDebug('Running query: %s', query.trim());
+        const psqlArgs = ['-c', query, '--set', 'sslmode=require', ...psqlCmdArgs];
+        const childProcessOptions = {
+            stdio: ['ignore', 'pipe', 'inherit'],
+        };
+        return {
+            childProcessOptions,
+            dbEnv,
+            psqlArgs,
+        };
+    }
+    /**
+     * Runs the psql command with tunnel support.
+     *
+     * @param tunnelConfig - The tunnel configuration object
+     * @param options - The options for spawning the psql process
+     * @returns Promise that resolves to the query result as a string
+     */
+    async runWithTunnel(tunnelConfig, options) {
+        const tunnel = await Tunnel.connect(this.connectionDetails, tunnelConfig, this.tunnelFn);
+        pgDebug('after create tunnel');
+        const psql = this.spawnPsql(options);
+        // Note: In non-interactive mode, psql.stdout is available for capturing output.
+        // In interactive mode, stdio: 'inherit' would make psql.stdout null.
+        // Return a string for consistency but ideally we should return the child process from this function
+        // and let the caller decide what to do with stdin/stdout/stderr
+        const stdoutPromise = psql.stdout ? this.consumeStream(psql.stdout) : Promise.resolve('');
+        const cleanupSignalTraps = this.trapAndForwardSignalsToChildProcess(psql);
+        try {
+            pgDebug('waiting for psql or tunnel to exit');
+            // wait for either psql or tunnel to exit;
+            // the important bit is that we ensure both processes are
+            // always cleaned up in the `finally` block below
+            await Promise.race([
+                this.waitForPSQLExit(psql),
+                tunnel.waitForClose(),
+            ]);
+        }
+        catch (error) {
+            pgDebug('wait for psql or tunnel error', error);
+            throw error;
+        }
+        finally {
+            pgDebug('begin tunnel cleanup');
+            cleanupSignalTraps();
+            tunnel.close();
+            this.kill(psql, 'SIGKILL');
+            pgDebug('end tunnel cleanup');
+        }
+        return stdoutPromise;
+    }
+    /**
+     * Spawns the psql process with the given options.
+     *
+     * @param options - The options for spawning the psql process
+     * @returns The spawned child process
+     */
+    spawnPsql(options) {
+        const { childProcessOptions, dbEnv, psqlArgs } = options;
+        const spawnOptions = {
+            env: dbEnv,
+            ...childProcessOptions,
+        };
+        pgDebug('opening psql process');
+        const psql = this.spawnFn('psql', psqlArgs, spawnOptions);
+        psql.once('spawn', () => pgDebug('psql process spawned'));
+        return psql;
+    }
+    /**
+     * Traps SIGINT so that ctrl+c can be used by psql without killing the parent node process.
+     * You can use ctrl+c in psql to kill running queries while keeping the psql process open.
+     * This code is to stop the parent node process (heroku CLI) from exiting.
+     * If the parent Heroku CLI node process exits, then psql will exit as it is a child process.
+     *
+     * @param childProcess - The child process to forward signals to
+     * @returns Function to restore the original signal handlers
+     */
+    trapAndForwardSignalsToChildProcess(childProcess) {
+        const signalsToTrap = ['SIGINT'];
+        const signalTraps = signalsToTrap.map(signal => {
+            process.removeAllListeners(signal);
+            const listener = () => this.kill(childProcess, signal);
+            process.on(signal, listener);
+            return [signal, listener];
+        });
+        // restores the built-in node ctrl+c and other handlers
+        return () => {
+            for (const [signal, listener] of signalTraps) {
+                process.removeListener(signal, listener);
+            }
+        };
+    }
+    /**
+     * Waits for the psql process to exit and handles any errors.
+     *
+     * @param psql - The psql process event emitter
+     * @throws Error if psql exits with non-zero code or if psql command is not found
+     * @returns Promise that resolves to void when psql exits
+     */
+    async waitForPSQLExit(psql) {
+        let errorToThrow = null;
+        try {
+            const [exitCode] = await once(psql, 'close');
+            pgDebug(`psql exited with code ${exitCode}`);
+            if (exitCode > 0) {
+                errorToThrow = new Error(`psql exited with code ${exitCode}`);
+            }
+        }
+        catch (error) {
+            pgDebug('psql process error', error);
+            const { code } = error;
+            if (code === 'ENOENT') {
+                errorToThrow = new Error('The local psql command could not be located. For help installing psql, see '
+                    + 'https://devcenter.heroku.com/articles/heroku-postgresql#local-setup');
+            }
+        }
+        if (errorToThrow) {
+            throw errorToThrow;
+        }
+    }
+}

package/dist/ux/table.d.ts

@@ -10,5 +10,5 @@ type Columns<T extends Record<string, unknown>> = {
 };
 export declare function table<T extends Record<string, unknown>>(data: T[], columns: Columns<T>, options?: {
     printLine?(s: unknown): void;
-} & Omit<TableOptions<T>, 'data'>): void;
+} & Omit<TableOptions<T>, 'columns' | 'data'>): void;
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@heroku/heroku-cli-util",
-  "version": "10.0.0-beta.2",
+  "version": "10.1.0",
   "description": "Set of helpful CLI utilities",
   "author": "Heroku",
   "license": "ISC",
@@ -11,8 +11,8 @@
     "dist"
   ],
   "devDependencies": {
-    "@heroku-cli/test-utils": "0.1.1",
     "@heroku-cli/schema": "^2.0.0",
+    "@heroku-cli/test-utils": "0.1.1",
     "@types/chai": "^4.3.13",
     "@types/chai-as-promised": "^8.0.2",
     "@types/debug": "^4.1.12",
@@ -20,7 +20,9 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.15.3",
     "@types/sinon": "^17.0.4",
+    "@types/sinon-chai": "^4.0.0",
     "@types/tunnel-ssh": "4.1.1",
+    "c8": "^7.7.0",
     "chai": "^4.4.1",
     "chai-as-promised": "^8.0.1",
     "eslint": "^8.57.0",
@@ -31,8 +33,8 @@
     "mocha": "^10.8.2",
     "mock-stdin": "^1.0.0",
     "nock": "^13.2.9",
-    "nyc": "^17.1.0",
     "sinon": "^18.0.1",
+    "sinon-chai": "^3.7.0",
     "strip-ansi": "^6",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
@@ -58,7 +60,7 @@
     "example": "sh examples/run.sh",
     "lint": "eslint . --ext .ts --config .eslintrc.cjs",
     "prepare": "npm run build",
-    "test": "nyc mocha --forbid-only \"test/**/*.test.ts\"",
-    "test:local": "nyc mocha \"${npm_config_file:-test/**/*.test.+(ts|tsx)}\""
+    "test": "c8 mocha --forbid-only \"test/**/*.test.ts\"",
+    "test:local": "c8 mocha \"${npm_config_file:-test/**/*.test.+(ts|tsx)}\""
   }
 }

package/dist/types/errors/ambiguous.d.ts

@@ -1,15 +0,0 @@
-export declare class AmbiguousError extends Error {
-    readonly matches: {
-        name?: string;
-    }[];
-    readonly type: string;
-    readonly body: {
-        id: string;
-        message: string;
-    };
-    readonly message: string;
-    readonly statusCode = 422;
-    constructor(matches: {
-        name?: string;
-    }[], type: string);
-}

package/dist/types/errors/not-found.d.ts

@@ -1,5 +0,0 @@
-export declare class NotFound extends Error {
-    readonly id = "not_found";
-    readonly message = "Couldn't find that addon.";
-    readonly statusCode = 404;
-}

package/dist/types/errors/not-found.js

@@ -1,5 +0,0 @@
-export class NotFound extends Error {
-    id = 'not_found';
-    message = 'Couldn\'t find that addon.';
-    statusCode = 404;
-}