@heroku/heroku-cli-util 9.0.0-beta.2 → 9.0.0

package/README.md

@@ -19,50 +19,97 @@ npm install @heroku/heroku-cli-util
 
 ## Usage
 
-You can import the utilities you need.
+You can import the utilities you need from the main exports.
 
 ### Output Utilities
 
 ```js
+import { hux } from '@heroku/heroku-cli-util';
+
 // Styled header
-import { styledHeader } from '@heroku/heroku-cli-util/dist/ux/styled-header';
-styledHeader('My CLI Header');
+hux.styledHeader('My CLI Header');
 
 // Styled JSON
-import { styledJSON } from '@heroku/heroku-cli-util/dist/ux/styled-json';
-styledJSON({ foo: 'bar' });
+hux.styledJson({ foo: 'bar' });
 
 // Styled object
-import { styledObject } from '@heroku/heroku-cli-util/dist/ux/styled-object';
-styledObject({ foo: 'bar' });
-
-// Table
-import { table } from '@heroku/heroku-cli-util/dist/ux/table';
-table([{ name: 'Alice' }, { name: 'Bob' }], { columns: [{ key: 'name' }] });
-
-// Wait
-import { wait } from '@heroku/heroku-cli-util/dist/ux/wait';
-await wait('Processing...');
+hux.styledObject({ foo: 'bar' });
 ```
 
 ### User Interaction
 
 ```js
-import { prompt } from '@heroku/heroku-cli-util/dist/ux/prompt';
-const name = await prompt('What is your name?');
+import { hux } from '@heroku/heroku-cli-util';
 
-import { confirm } from '@heroku/heroku-cli-util/dist/ux/confirm';
-const proceed = await confirm('Continue?');
+const name = await hux.prompt('What is your name?');
+const proceed = await hux.confirm('Continue?');
 ```
 
 ### Test Helpers
 
 ```js
-import { initCliTest } from '@heroku/heroku-cli-util/dist/test-helpers/init';
-initCliTest();
+import { testHelpers } from '@heroku/heroku-cli-util';
+
+testHelpers.initCliTest();
+
+testHelpers.setupStdoutStderr();
+// ...run your CLI code...
+const output = testHelpers.stdout();
+const errorOutput = testHelpers.stderr();
+testHelpers.restoreStdoutStderr();
+
+testHelpers.expectOutput(output, 'expected output');
+
+// Run a command (see docs for details)
+// await testHelpers.runCommand(MyCommand, ['arg1', 'arg2']);
+```
+
+### Types
+
+```js
+import { types } from '@heroku/heroku-cli-util';
+
+// Error types
+try {
+  throw new types.errors.AmbiguousError([{ name: 'foo' }, { name: 'bar' }], 'addon');
+} catch (err) {
+  if (err instanceof types.errors.AmbiguousError) {
+    console.error('Ambiguous:', err.message);
+  }
+}
+
+try {
+  throw new types.errors.NotFound();
+} catch (err) {
+  if (err instanceof types.errors.NotFound) {
+    console.error('Not found:', err.message);
+  }
+}
+
+// PG types (for TypeScript)
+/**
+ * types.pg.AddOnAttachmentWithConfigVarsAndPlan
+ * types.pg.AddOnWithRelatedData
+ * types.pg.ConnectionDetails
+ * types.pg.ConnectionDetailsWithAttachment
+ * types.pg.Link
+ * types.pg.TunnelConfig
+ */
+```
+
+### Database and Utility Helpers
+
+```js
+import { utils } from '@heroku/heroku-cli-util';
+
+// Get Heroku Postgres database connection details (requires APIClient from @heroku-cli/command)
+// const db = await utils.pg.databases(herokuApiClient, 'my-app', 'DATABASE_URL');
+
+// Get Heroku Postgres host
+const host = utils.pg.host();
 
-import { stdout, stderr } from '@heroku/heroku-cli-util/dist/test-helpers/stub-output';
-// Use stdout() and stderr() in your tests to capture CLI output
+// Run a query (requires a ConnectionDetails object)
+// const result = await utils.pg.psql.exec(db, 'SELECT 1');
 ```
 
 ## Development

package/dist/index.d.ts

@@ -1,28 +1,53 @@
 import { initCliTest } from './test-helpers/init';
 import { restoreStdoutStderr, setupStdoutStderr, stderr, stdout } from './test-helpers/stub-output';
+import { AmbiguousError } from './types/errors/ambiguous';
+import { NotFound } from './types/errors/not-found';
+import { AddOnAttachmentWithConfigVarsAndPlan, AddOnWithRelatedData, Link } from './types/pg/data-api';
+import { ConnectionDetails, ConnectionDetailsWithAttachment, TunnelConfig } from './types/pg/tunnel';
+import { getDatabase } from './utils/pg/databases';
+import getHost from './utils/pg/host';
+import { exec } from './utils/pg/psql';
+import { confirm } from './ux/confirm';
+import { prompt } from './ux/prompt';
+import { styledHeader } from './ux/styled-header';
+import { styledJson } from './ux/styled-json';
+import { styledObject } from './ux/styled-object';
 export declare const testHelpers: {
     expectOutput: (actual: string, expected: string) => Chai.Assertion;
     initCliTest: typeof initCliTest;
     restoreStdoutStderr: typeof restoreStdoutStderr;
+    runCommand: (Cmd: import("./test-helpers/run-command").GenericCmd, args?: string[], printStd?: boolean) => Promise<any>;
     setupStdoutStderr: typeof setupStdoutStderr;
     stderr: typeof stderr;
     stdout: typeof stdout;
 };
-export { default as expectOutput } from './test-helpers/expect-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';
+export declare const types: {
+    errors: {
+        AmbiguousError: typeof AmbiguousError;
+        NotFound: typeof NotFound;
+    };
+    pg: {
+        AddOnAttachmentWithConfigVarsAndPlan: AddOnAttachmentWithConfigVarsAndPlan;
+        AddOnWithRelatedData: AddOnWithRelatedData;
+        ConnectionDetails: ConnectionDetails;
+        ConnectionDetailsWithAttachment: ConnectionDetailsWithAttachment;
+        Link: Link;
+        TunnelConfig: TunnelConfig;
+    };
+};
+export declare const utils: {
+    pg: {
+        databases: typeof getDatabase;
+        host: typeof getHost;
+        psql: {
+            exec: typeof exec;
+        };
+    };
+};
+export declare const hux: {
+    confirm: typeof confirm;
+    prompt: typeof prompt;
+    styledHeader: typeof styledHeader;
+    styledJson: typeof styledJson;
+    styledObject: typeof styledObject;
+};

package/dist/index.js

@@ -1,40 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPgHost = exports.expectOutput = exports.testHelpers = void 0;
-const tslib_1 = require("tslib");
-// Test helpers (optional, for test environments)
+exports.hux = exports.utils = exports.types = exports.testHelpers = void 0;
 const expect_output_1 = require("./test-helpers/expect-output");
 const init_1 = require("./test-helpers/init");
+const run_command_1 = require("./test-helpers/run-command");
 const stub_output_1 = require("./test-helpers/stub-output");
+const ambiguous_1 = require("./types/errors/ambiguous");
+const not_found_1 = require("./types/errors/not-found");
+const databases_1 = require("./utils/pg/databases");
+const host_1 = require("./utils/pg/host");
+const psql_1 = require("./utils/pg/psql");
+const confirm_1 = require("./ux/confirm");
+const prompt_1 = require("./ux/prompt");
+const styled_header_1 = require("./ux/styled-header");
+const styled_json_1 = require("./ux/styled-json");
+const styled_object_1 = require("./ux/styled-object");
 exports.testHelpers = {
     expectOutput: expect_output_1.default,
     initCliTest: init_1.initCliTest,
     restoreStdoutStderr: stub_output_1.restoreStdoutStderr,
+    runCommand: run_command_1.runCommand,
     setupStdoutStderr: stub_output_1.setupStdoutStderr,
     stderr: stub_output_1.stderr,
     stdout: stub_output_1.stdout,
 };
-var expect_output_2 = require("./test-helpers/expect-output");
-Object.defineProperty(exports, "expectOutput", { enumerable: true, get: function () { return expect_output_2.default; } });
-// 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);
+exports.types = {
+    errors: {
+        AmbiguousError: ambiguous_1.AmbiguousError,
+        NotFound: not_found_1.NotFound,
+    },
+    pg: {
+        AddOnAttachmentWithConfigVarsAndPlan: {},
+        AddOnWithRelatedData: {},
+        ConnectionDetails: {},
+        ConnectionDetailsWithAttachment: {},
+        Link: {},
+        TunnelConfig: {},
+    },
+};
+exports.utils = {
+    pg: {
+        databases: databases_1.getDatabase,
+        host: host_1.default,
+        psql: {
+            exec: psql_1.exec,
+        },
+    },
+};
+exports.hux = {
+    confirm: confirm_1.confirm,
+    prompt: prompt_1.prompt,
+    styledHeader: styled_header_1.styledHeader,
+    styledJson: styled_json_1.styledJson,
+    styledObject: styled_object_1.styledObject,
+};

package/dist/test-helpers/init.js

@@ -2,7 +2,6 @@
 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() {

package/dist/test-helpers/run-command.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@heroku-cli/command';
+import { APIClient } from '@heroku-cli/command';
+import { Config } from '@oclif/core';
+type CmdConstructorParams = ConstructorParameters<typeof Command>;
+export type GenericCmd = new (...args: CmdConstructorParams) => Command;
+export declare const runCommand: (Cmd: GenericCmd, args?: string[], printStd?: boolean) => Promise<any>;
+export declare const getConfig: () => Promise<Config>;
+export declare const getHerokuAPI: () => Promise<APIClient>;
+export {};

package/dist/test-helpers/run-command.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHerokuAPI = exports.getConfig = exports.runCommand = void 0;
+const command_1 = require("@heroku-cli/command");
+const core_1 = require("@oclif/core");
+const stdout_stderr_1 = require("stdout-stderr");
+const stopMock = () => {
+    stdout_stderr_1.stdout.stop();
+    stdout_stderr_1.stderr.stop();
+};
+const runCommand = async (Cmd, args = [], printStd = false) => {
+    const conf = await (0, exports.getConfig)();
+    const instance = new Cmd(args, conf);
+    if (printStd) {
+        stdout_stderr_1.stdout.print = true;
+        stdout_stderr_1.stderr.print = true;
+    }
+    stdout_stderr_1.stdout.start();
+    stdout_stderr_1.stderr.start();
+    return instance
+        .run()
+        .then(args => {
+        stopMock();
+        return args;
+    })
+        .catch((error) => {
+        stopMock();
+        throw error;
+    });
+};
+exports.runCommand = runCommand;
+const getConfig = async () => {
+    const pjsonPath = require.resolve('../../package.json');
+    const conf = new core_1.Config({ root: pjsonPath });
+    await conf.load();
+    return conf;
+};
+exports.getConfig = getConfig;
+const getHerokuAPI = async () => {
+    const conf = await (0, exports.getConfig)();
+    return new command_1.APIClient(conf);
+};
+exports.getHerokuAPI = getHerokuAPI;

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "commonjs",
   "name": "@heroku/heroku-cli-util",
-  "version": "9.0.0-beta.2",
+  "version": "9.0.0",
   "description": "Set of helpful CLI utilities",
   "author": "Heroku",
   "license": "ISC",
@@ -13,12 +13,14 @@
   "devDependencies": {
     "@heroku-cli/schema": "^2.0.0",
     "@types/chai": "^4.3.13",
+    "@types/chai-as-promised": "^8.0.2",
     "@types/debug": "^4.1.12",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.15.3",
     "@types/sinon": "^17.0.4",
     "@types/tunnel-ssh": "4.1.1",
     "chai": "^4.4.1",
+    "chai-as-promised": "^8.0.1",
     "eslint": "^8.57.0",
     "eslint-config-oclif": "^5.0.0",
     "eslint-config-oclif-typescript": "^3.1.14",
@@ -34,12 +36,13 @@
     "typescript": "^5.4.0"
   },
   "dependencies": {
-    "@oclif/core": "^2.16.0",
-    "@heroku/http-call": "^5.4.0",
     "@heroku-cli/color": "^2.0.4",
     "@heroku-cli/command": "^11.5.0",
+    "@heroku/http-call": "^5.4.0",
+    "@oclif/core": "^2.16.0",
     "debug": "^4.4.0",
     "nock": "^13.2.9",
+    "stdout-stderr": "^0.1.13",
     "tunnel-ssh": "4.1.6"
   },
   "engines": {
@@ -48,7 +51,8 @@
   "mocha": {
     "require": [
       "ts-node/register",
-      "source-map-support/register"
+      "source-map-support/register",
+      "test/hooks.ts"
     ],
     "file": [
       "src/test-helpers/stub-output.ts"
@@ -59,10 +63,10 @@
     "timeout": 360000
   },
   "scripts": {
-    "build": "tsc",
+    "build": "npm run clean && tsc",
     "clean": "rm -rf dist",
     "lint": "eslint . --ext .ts --config .eslintrc.js",
-    "prepare": "npm run clean && npm run build",
+    "prepare": "npm run build",
     "test": "nyc mocha  --forbid-only \"test/**/*.test.ts\"",
     "test:local": "mocha \"test/**/*.test.ts\""
   }