@heroku/heroku-cli-util 9.0.2 → 9.1.0

package/dist/utils/pg/psql.js

@@ -1,162 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Tunnel = exports.trapAndForwardSignalsToChildProcess = void 0;
-exports.consumeStream = consumeStream;
-exports.exec = exec;
-exports.psqlQueryOptions = psqlQueryOptions;
-exports.execPSQL = execPSQL;
-exports.runWithTunnel = runWithTunnel;
-exports.waitForPSQLExit = waitForPSQLExit;
-const debug_1 = require("debug");
+exports.Tunnel = void 0;
+const tslib_1 = require("tslib");
+const debug_1 = tslib_1.__importDefault(require("debug"));
 const node_child_process_1 = require("node:child_process");
 const node_events_1 = require("node:events");
 const node_stream_1 = require("node:stream");
 const promises_1 = require("node:stream/promises");
 const bastion_1 = require("./bastion");
 const pgDebug = (0, debug_1.default)('pg');
-function consumeStream(inputStream) {
-    let result = '';
-    const throughStream = new node_stream_1.Stream.PassThrough();
-    // eslint-disable-next-line no-async-promise-executor
-    const promise = new Promise(async (resolve, reject) => {
-        try {
-            await (0, promises_1.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;
-}
-async function exec(db, query, cmdArgs = []) {
-    const configs = (0, bastion_1.getConfigs)(db);
-    const options = psqlQueryOptions(query, configs.dbEnv, cmdArgs);
-    return runWithTunnel(db, configs.dbTunnelConfig, options);
-}
-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,
-    };
-}
-function execPSQL({ childProcessOptions, dbEnv, psqlArgs }) {
-    const options = Object.assign({ env: dbEnv }, childProcessOptions);
-    pgDebug('opening psql process');
-    const psql = (0, node_child_process_1.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);
-    }
-}
-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 = (0, exports.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.
-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);
-        }
-    };
-};
-exports.trapAndForwardSignalsToChildProcess = trapAndForwardSignalsToChildProcess;
-async function waitForPSQLExit(psql) {
-    let errorToThrow = null;
-    try {
-        const [exitCode] = await (0, node_events_1.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.
+ */
 class Tunnel {
+    /**
+     * 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 node_events_1.EventEmitter();
     }
-    static async connect(db, tunnelConfig) {
-        const tunnel = await (0, bastion_1.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');
@@ -167,6 +50,12 @@ 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 {
@@ -180,9 +69,198 @@ class Tunnel {
             }
         }
         else {
-            pgDebug('no bastion required; waiting for fake close event');
+            pgDebug('no tunnel required; waiting for fake close event');
             await (0, node_events_1.once)(this.events, 'close');
         }
     }
 }
 exports.Tunnel = Tunnel;
+class PsqlService {
+    constructor(connectionDetails, getPsqlConfigsFn = bastion_1.getPsqlConfigs, spawnFn = node_child_process_1.spawn, tunnelFn = bastion_1.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 node_stream_1.Stream.PassThrough();
+        // eslint-disable-next-line no-async-promise-executor
+        const promise = new Promise(async (resolve, reject) => {
+            try {
+                await (0, promises_1.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 = Object.assign({ 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 (0, node_events_1.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;
+        }
+    }
+}
+exports.default = PsqlService;

package/package.json

@@ -1,7 +1,6 @@
 {
-  "type": "commonjs",
   "name": "@heroku/heroku-cli-util",
-  "version": "9.0.2",
+  "version": "9.1.0",
   "description": "Set of helpful CLI utilities",
   "author": "Heroku",
   "license": "ISC",
@@ -19,9 +18,10 @@
     "@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",
     "chai": "^4.4.1",
-    "chai-as-promised": "^8.0.1",
+    "chai-as-promised": "^7.1.2",
     "eslint": "^8.57.0",
     "eslint-config-oclif": "^5.0.0",
     "eslint-config-oclif-typescript": "^3.1.14",
@@ -31,6 +31,7 @@
     "nock": "^13.2.9",
     "nyc": "^17.1.0",
     "sinon": "^18.0.1",
+    "sinon-chai": "^3.7.0",
     "stdout-stderr": "^0.1.13",
     "strip-ansi": "^6",
     "ts-node": "^10.9.2",
@@ -49,17 +50,6 @@
   "engines": {
     "node": ">=20"
   },
-  "mocha": {
-    "require": [
-      "ts-node/register",
-      "source-map-support/register",
-      "test/hooks.ts"
-    ],
-    "watch-extensions": "ts",
-    "recursive": true,
-    "reporter": "spec",
-    "timeout": 360000
-  },
   "scripts": {
     "build": "npm run clean && tsc",
     "clean": "rm -rf dist",

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,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.NotFound = void 0;
-class NotFound extends Error {
-    constructor() {
-        super(...arguments);
-        this.id = 'not_found';
-        this.message = 'Couldn\'t find that addon.';
-        this.statusCode = 404;
-    }
-}
-exports.NotFound = NotFound;