@heroku/heroku-cli-util 8.0.15 → 9.0.0-beta.1

package/LICENSE

@@ -1,3 +1,15 @@
-Copyright (c) 2016, Heroku
-Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+The ISC License (ISC)
+
+Copyright © Heroku 2008 - 2025
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,269 +1,72 @@
-# Heroku CLI Utilities
+# @heroku/heroku-cli-util
 
-![GitHub Actions CI](https://github.com/heroku/heroku-cli-util/actions/workflows/ci.yml/badge.svg)
-[![npm version](https://badge.fury.io/js/heroku-cli-util.svg)](http://badge.fury.io/js/heroku-cli-util)
-[![License](https://img.shields.io/github/license/heroku/heroku-cli-util.svg)](https://github.com/heroku/heroku-cli-util/blob/master/LICENSE)
+A set of helpful CLI utilities for Heroku and oclif-based Node.js CLIs. This
+package provides convenient wrappers and helpers for user interaction, output
+formatting, and test utilities.
 
-Set of helpful CLI utilities
+## Features
 
-## Installation
-
-```sh
-npm install heroku-cli-util --save
-```
-
-## Action
-
-```js
-let cli = require('heroku-cli-util');
-await cli.action('restarting dynos', async function() {
-  let app = await heroku.get(`/apps/${context.app}`);
-  await heroku.request({method: 'DELETE', path: `/apps/${app.name}/dynos`});
-});
-
-// restarting dynos... done
-```
-
-## Prompt
-
-```js
-let cli   = require('heroku-cli-util');
-let email = await cli.prompt('email', {});
-console.log(`your email is: ${email}`);
-```
-
-**cli.prompt options**
-
-```js
-cli.prompt('email', {
-  mask: true, // mask input field after submitting
-  hide: true // mask characters while entering
-});
-```
-
-## Confirm App
-
-Supports the same async styles as `prompt()`. Errors if not confirmed.
-
-Basic
-
-```js
-let cli = require('heroku-cli-util');
-await cli.confirmApp('appname', context.flags.confirm);
-
-// !     WARNING: Destructive Action
-// !     This command will affect the app appname
-// !     To proceed, type appname or re-run this command with --confirm appname
-
-> appname
-```
-
-Custom message
-
-```js
-let cli = require('heroku-cli-util');
-await cli.confirmApp('appname', context.flags.confirm, 'foo');
-
-// !     foo
-// !     To proceed, type appname or re-run this command with --confirm appname
-
-> appname
-```
-
-Note that you will still need to define a `confirm` flag for your command.
-
-## Errors
-
-```js
-let cli = require('heroku-cli-util');
-cli.error("App not found");
-// !    App not found
-```
-
-## Warnings
-
-```js
-let cli = require('heroku-cli-util');
-cli.warn("App not found");
-// !    App not found
-```
-
-## Dates
-
-```js
-let cli = require('heroku-cli-util');
-let d   = new Date();
-console.log(cli.formatDate(d));
-// 2001-01-01T08:00:00.000Z
-```
-
-## Hush
-
-Use hush for verbose logging when `HEROKU_DEBUG=1`.
-
-```js
-let cli = require('heroku-cli-util');
-cli.hush('foo');
-// only prints if HEROKU_DEBUG is set
-```
-
-## Debug
-
-Pretty print an object.
-
-```js
-let cli = require('heroku-cli-util');
-cli.debug({foo: [1,2,3]});
-// { foo: [ 1, 2, 3 ] }
-```
-
-## Stylized output
-
-Pretty print a header, hash, and JSON
-```js
-let cli = require('heroku-cli-util');
-cli.styledHeader("MyApp");
-cli.styledHash({name: "myapp", collaborators: ["user1@example.com", "user2@example.com"]});
-cli.styledJSON({name: "myapp"});
-```
-
-Produces
-
-```
-=== MyApp
-Collaborators: user1@example.com
-               user1@example.com
-Name:          myapp
-
-{
-  "name": "myapp"
-}
-```
+- **User prompts and confirmations** (yes/no, input)
+- **Styled output** (headers, JSON, objects, tables)
+- **Wait indicators** for async operations
+- **Test helpers** for CLI output and environment setup
 
-## Table
+## Installation
 
-```js
-cli.table([
-  {app: 'first-app',  language: 'ruby', dyno_count: 3},
-  {app: 'second-app', language: 'node', dyno_count: 2},
-], {
-  columns: [
-    {key: 'app'},
-    {key: 'dyno_count', label: 'Dyno Count'},
-    {key: 'language', format: language => cli.color.red(language)},
-  ]
-});
+```bash
+npm install @heroku/heroku-cli-util
 ```
 
-Produces:
-
-```
-app         Dyno Count  language
-──────────  ──────────  ────────
-first-app   3           ruby
-second-app  2           node
-```
+## Usage
 
-## Linewrap
+You can import the utilities you need.
 
-Used to indent output with wrapping around words:
+### Output Utilities
 
 ```js
-cli.log(cli.linewrap(2, 10, 'this is text is longer than 10 characters'));
-// Outputs:
-//
-// this
-// text is
-//  longer
-//  than 10
-//  characters`);
-```
-
-Useful with `process.stdout.columns || 80`.
-
-## Open Web Browser
+// Styled header
+import { styledHeader } from '@heroku/heroku-cli-util/dist/ux/styled-header';
+styledHeader('My CLI Header');
 
-```js
-await cli.open('https://github.com');
-```
+// Styled JSON
+import { styledJSON } from '@heroku/heroku-cli-util/dist/ux/styled-json';
+styledJSON({ foo: 'bar' });
 
-## HTTP calls
+// Styled object
+import { styledObject } from '@heroku/heroku-cli-util/dist/ux/styled-object';
+styledObject({ foo: 'bar' });
 
-`heroku-cli-util` includes an instance of [got](https://www.npmjs.com/package/got) that will correctly use HTTP proxies.
+// Table
+import { table } from '@heroku/heroku-cli-util/dist/ux/table';
+table([{ name: 'Alice' }, { name: 'Bob' }], { columns: [{ key: 'name' }] });
 
-```js
-let cli = require('heroku-cli-util');
-let rsp = await cli.got('https://google.com');
+// Wait
+import { wait } from '@heroku/heroku-cli-util/dist/ux/wait';
+await wait('Processing...');
 ```
 
-## Mocking
-
-Mock stdout and stderr by using `cli.log()` and `cli.error()`.
+### User Interaction
 
 ```js
-let cli = require('heroku-cli-util');
-cli.log('message 1'); // prints 'message 1'
-cli.mockConsole();
-cli.log('message 2'); // prints nothing
-cli.stdout.should.eq('message 2\n');
-```
-
-## Command
-
-Used for initializing a plugin command.
-give you an auth'ed instance of `heroku-client` and cleanly handle API exceptions.
+import { prompt } from '@heroku/heroku-cli-util/dist/ux/prompt';
+const name = await prompt('What is your name?');
 
-It expects you to return a promise chain. This is usually done with [co](https://github.com/tj/co).
-
-```js
-let cli = require('heroku-cli-util');
-let co  = require('co');
-module.exports.commands = [
-  {
-    topic: 'apps',
-    command: 'info',
-    needsAuth: true,
-    needsApp: true,
-    run: cli.command(async function (context, heroku) {
-      let app = await heroku.get(`/apps/${context.app}`);
-      console.dir(app);
-    })
-  }
-];
+import { confirm } from '@heroku/heroku-cli-util/dist/ux/confirm';
+const proceed = await confirm('Continue?');
 ```
 
-With options:
+### Test Helpers
 
 ```js
-let cli = require('heroku-cli-util');
-let co  = require('co');
-module.exports.commands = [
-  {
-    topic: 'apps',
-    command: 'info',
-    needsAuth: true,
-    needsApp: true,
-    run: cli.command(
-      {preauth: true},
-      async function (context, heroku) {
-        let app = await heroku.get(`/apps/${context.app}`);
-        console.dir(app);
-      }
-    )
-  }
-];
-```
-
-If the command has a `two_factor` API error, it will ask the user for a 2fa code and retry.
-If you set `preauth: true` it will preauth against the current app instead of just setting the header on an app. (This is necessary if you need to do more than 1 API call that will require 2fa)
-
-## Tests
+import { initCliTest } from '@heroku/heroku-cli-util/dist/test-helpers/init';
+initCliTest();
 
-```sh
-npm install
-npm test
+import { stdout, stderr } from '@heroku/heroku-cli-util/dist/test-helpers/stub-output';
+// Use stdout() and stderr() in your tests to capture CLI output
 ```
 
-## License
+## Development
 
-ISC
+- Build: `npm run build`
+- Test: `npm test`
+- Lint: `npm run lint`

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { default as expectOutput } from './test-helpers/expect-output';
+export * from './test-helpers/init';
+export * from './test-helpers/stub-output';
+export * from './types/errors/ambiguous';
+export * from './types/errors/not-found';
+export * from './types/pg/data-api';
+export * from './types/pg/tunnel';
+export * from './utils/addons/resolve';
+export * from './utils/pg/bastion';
+export * from './utils/pg/config-vars';
+export * from './utils/pg/databases';
+export { default as getPgHost } from './utils/pg/host';
+export * from './utils/pg/psql';
+export * from './ux/confirm';
+export * from './ux/prompt';
+export * from './ux/styled-header';
+export * from './ux/styled-json';
+export * from './ux/styled-object';
+export * from './ux/table';
+export * from './ux/wait';

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPgHost = exports.expectOutput = void 0;
+const tslib_1 = require("tslib");
+// Test helpers (optional, for test environments)
+var expect_output_1 = require("./test-helpers/expect-output");
+Object.defineProperty(exports, "expectOutput", { enumerable: true, get: function () { return expect_output_1.default; } });
+tslib_1.__exportStar(require("./test-helpers/init"), exports);
+tslib_1.__exportStar(require("./test-helpers/stub-output"), exports);
+// Types - Errors
+tslib_1.__exportStar(require("./types/errors/ambiguous"), exports);
+tslib_1.__exportStar(require("./types/errors/not-found"), exports);
+// Types - PG
+tslib_1.__exportStar(require("./types/pg/data-api"), exports);
+tslib_1.__exportStar(require("./types/pg/tunnel"), exports);
+tslib_1.__exportStar(require("./utils/addons/resolve"), exports);
+// Utilities - Postgres
+tslib_1.__exportStar(require("./utils/pg/bastion"), exports);
+tslib_1.__exportStar(require("./utils/pg/config-vars"), exports);
+tslib_1.__exportStar(require("./utils/pg/databases"), exports);
+var host_1 = require("./utils/pg/host");
+Object.defineProperty(exports, "getPgHost", { enumerable: true, get: function () { return host_1.default; } });
+tslib_1.__exportStar(require("./utils/pg/psql"), exports);
+// UX helpers
+tslib_1.__exportStar(require("./ux/confirm"), exports);
+tslib_1.__exportStar(require("./ux/prompt"), exports);
+tslib_1.__exportStar(require("./ux/styled-header"), exports);
+tslib_1.__exportStar(require("./ux/styled-json"), exports);
+tslib_1.__exportStar(require("./ux/styled-object"), exports);
+tslib_1.__exportStar(require("./ux/table"), exports);
+tslib_1.__exportStar(require("./ux/wait"), exports);

package/dist/test-helpers/expect-output.d.ts

@@ -0,0 +1,2 @@
+declare const expectOutput: (actual: string, expected: string) => Chai.Assertion;
+export default expectOutput;

package/dist/test-helpers/expect-output.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+function stripIndents(str) {
+    str = str.trim().replace(/\s+$/gm, '');
+    const indent = (str.match(/^\s+[^$]/m) || [''])[0].length - 1;
+    const regexp = new RegExp(`^s{${indent}}`, 'mg');
+    return str.replace(regexp, '');
+}
+const expectOutput = function (actual, expected) {
+    // it can be helpful to strip all hyphens & spaces when migrating tests before perfecting
+    // use `.replace(/[\s─]/g, '')` on both actual & expected until tests pass, then remove, and paste actual into expected
+    return (0, chai_1.expect)(actual.trim().replace(/\s+$/gm, ''))
+        .to.equal(stripIndents(expected));
+};
+exports.default = expectOutput;

package/dist/test-helpers/init.d.ts

@@ -0,0 +1 @@
+export declare function initCliTest(): void;

package/dist/test-helpers/init.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCliTest = initCliTest;
+const path = require('node:path');
+// eslint-disable-next-line n/no-missing-require
+const { color } = require('@heroku-cli/color');
+const nock = require('nock');
+function initCliTest() {
+    // eslint-disable-next-line no-multi-assign
+    process.env.TS_NODE_PROJECT = path.resolve('test/tsconfig.json');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    global.columns = '120';
+    color.enabled = false;
+    nock.disableNetConnect();
+    if (process.env.ENABLE_NET_CONNECT === 'true') {
+        nock.enableNetConnect();
+    }
+}

package/dist/test-helpers/stub-output.d.ts

@@ -0,0 +1,2 @@
+export declare function stdout(): string;
+export declare function stderr(): string;

package/dist/test-helpers/stub-output.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stdout = stdout;
+exports.stderr = stderr;
+const sinon = require("sinon");
+let stdoutWriteStub;
+let stdoutOutput = '';
+let stderrWriteStub;
+let stderrOutput = '';
+beforeEach(function () {
+    stdoutOutput = '';
+    stdoutWriteStub = sinon.stub(process.stdout, 'write').callsFake((str) => {
+        stdoutOutput += str.toString();
+        return true;
+    });
+    stderrOutput = '';
+    stderrWriteStub = sinon.stub(process.stderr, 'write').callsFake((str) => {
+        stderrOutput += str.toString();
+        return true;
+    });
+});
+afterEach(function () {
+    stdoutWriteStub.restore();
+    stdoutOutput = '';
+    stderrWriteStub.restore();
+    stderrOutput = '';
+});
+function stdout() {
+    return stdoutOutput;
+}
+function stderr() {
+    return stderrOutput;
+}

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

@@ -0,0 +1,15 @@
+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/ambiguous.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmbiguousError = void 0;
+class AmbiguousError extends Error {
+    constructor(matches, type) {
+        super();
+        this.matches = matches;
+        this.type = type;
+        this.body = { id: 'multiple_matches', message: this.message };
+        this.statusCode = 422;
+        this.message = `Ambiguous identifier; multiple matching add-ons found: ${matches.map(match => match.name).join(', ')}.`;
+    }
+}
+exports.AmbiguousError = AmbiguousError;

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,12 @@
+"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;

package/dist/types/pg/data-api.d.ts

@@ -0,0 +1,17 @@
+import * as Heroku from '@heroku-cli/schema';
+export type AddOnWithRelatedData = {
+    attachment_names?: string[];
+    links?: Link[];
+    plan: Required<Heroku.AddOn['plan']>;
+} & Required<Heroku.AddOnAttachment['addon']>;
+export type AddOnAttachmentWithConfigVarsAndPlan = {
+    addon: AddOnWithRelatedData;
+    config_vars: Heroku.AddOn['config_vars'];
+} & Required<Heroku.AddOnAttachment>;
+export type Link = {
+    attachment_name?: string;
+    created_at: string;
+    message: string;
+    name: string;
+    remote?: Link;
+};

package/dist/types/pg/data-api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/pg/tunnel.d.ts

@@ -0,0 +1,22 @@
+import type { AddOnAttachment } from '@heroku-cli/schema';
+import { Server } from 'node:net';
+import * as createTunnel from 'tunnel-ssh';
+import type { AddOnAttachmentWithConfigVarsAndPlan } from './data-api';
+export type ConnectionDetails = {
+    _tunnel?: Server;
+    bastionHost?: string;
+    bastionKey?: string;
+    database: string;
+    host: string;
+    password: string;
+    pathname: string;
+    port: string;
+    url: string;
+    user: string;
+};
+export type ConnectionDetailsWithAttachment = {
+    attachment: Required<{
+        addon: AddOnAttachmentWithConfigVarsAndPlan;
+    } & AddOnAttachment>;
+} & ConnectionDetails;
+export type TunnelConfig = createTunnel.Config;

package/dist/types/pg/tunnel.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/addons/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { APIClient } from '@heroku-cli/command';
+import type { AddOnAttachment } from '@heroku-cli/schema';
+import type { AddOnAttachmentWithConfigVarsAndPlan } from '../../types/pg/data-api';
+export declare const appAttachment: (heroku: APIClient, app: string | undefined, id: string, options?: {
+    addon_service?: string;
+    namespace?: string;
+}) => Promise<{
+    addon: AddOnAttachmentWithConfigVarsAndPlan;
+} & AddOnAttachment>;

package/dist/utils/addons/resolve.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appAttachment = void 0;
+const ambiguous_1 = require("../../types/errors/ambiguous");
+const not_found_1 = require("../../types/errors/not-found");
+const appAttachment = async (heroku, app, id, options = {}) => {
+    const result = await heroku.post('/actions/addon-attachments/resolve', {
+        // eslint-disable-next-line camelcase
+        body: { addon_attachment: id, addon_service: options.addon_service, app }, headers: attachmentHeaders,
+    });
+    return singularize('addon_attachment', options.namespace)(result.body);
+};
+exports.appAttachment = appAttachment;
+const attachmentHeaders = {
+    Accept: 'application/vnd.heroku+json; version=3.sdk',
+    'Accept-Inclusion': 'addon:plan,config_vars',
+};
+function singularize(type, namespace) {
+    return (matches) => {
+        if (namespace) {
+            matches = matches.filter(m => m.namespace === namespace);
+        }
+        else if (matches.length > 1) {
+            // In cases that aren't specific enough, filter by namespace
+            matches = matches.filter(m => !Reflect.has(m, 'namespace') || m.namespace === null);
+        }
+        switch (matches.length) {
+            case 0: {
+                throw new not_found_1.NotFound();
+            }
+            case 1: {
+                return matches[0];
+            }
+            default: {
+                throw new ambiguous_1.AmbiguousError(matches, type !== null && type !== void 0 ? type : '');
+            }
+        }
+    };
+}

package/dist/utils/pg/bastion.d.ts

@@ -0,0 +1,30 @@
+import type { APIClient } from '@heroku-cli/command';
+import * as createTunnel from 'tunnel-ssh';
+import { AddOnAttachmentWithConfigVarsAndPlan } from '../../types/pg/data-api';
+import { ConnectionDetails } from '../../types/pg/tunnel';
+import { TunnelConfig } from '../../types/pg/tunnel';
+export declare const bastionKeyPlan: (a: AddOnAttachmentWithConfigVarsAndPlan) => boolean;
+export declare const env: (db: ConnectionDetails) => {
+    TZ?: string;
+    PGAPPNAME: string;
+    PGSSLMODE: string;
+};
+export declare function fetchConfig(heroku: APIClient, db: {
+    id: string;
+}): Promise<import("@heroku/http-call").HTTP<{
+    host: string;
+    private_key: string;
+}>>;
+export declare const getBastion: (config: Record<string, string>, baseName: string) => {
+    bastionHost: string;
+    bastionKey: string;
+} | {
+    bastionHost?: undefined;
+    bastionKey?: undefined;
+};
+export declare function getConfigs(db: ConnectionDetails): {
+    dbEnv: NodeJS.ProcessEnv;
+    dbTunnelConfig: createTunnel.Config;
+};
+export declare function sshTunnel(db: ConnectionDetails, dbTunnelConfig: TunnelConfig, timeout?: number): Promise<void | import("net").Server | null>;
+export declare function tunnelConfig(db: ConnectionDetails): TunnelConfig;