@heroku/heroku-cli-util 10.6.1 → 10.7.0-beta.0

package/README.md

@@ -19,24 +19,38 @@ npm install @heroku/heroku-cli-util
 
 ## Usage
 
-You can import the utilities you need from the main exports.
+Import only the utilities you need for better performance and smaller bundle sizes.
+
+```js
+import * as color from '@heroku/heroku-cli-util/color';
+import { confirm, table } from '@heroku/heroku-cli-util/hux';
+import { DatabaseResolver } from '@heroku/heroku-cli-util/utils/pg';
+import { AddonResolver } from '@heroku/heroku-cli-util/utils/addons';
+```
+
+**Available import paths:**
+- `@heroku/heroku-cli-util/color` - Color utilities
+- `@heroku/heroku-cli-util/hux` - UX utilities (prompts, tables, output formatting)
+- `@heroku/heroku-cli-util/utils` - All utility functions
+- `@heroku/heroku-cli-util/utils/pg` - PostgreSQL-specific utilities
+- `@heroku/heroku-cli-util/utils/addons` - Addon-specific utilities
 
 ### Output Utilities
 
 ```js
-import { hux } from '@heroku/heroku-cli-util';
+import { styledHeader, styledJSON, styledObject, table, wait } from '@heroku/heroku-cli-util/hux';
 
 // Styled header
-hux.styledHeader('My CLI Header');
+styledHeader('My CLI Header');
 
 // Styled JSON
-hux.styledJSON({ foo: 'bar' });
+styledJSON({ foo: 'bar' });
 
 // Styled object
-hux.styledObject({ foo: 'bar' });
+styledObject({ foo: 'bar' });
 
 // Table output
-hux.table([
+table([
   {name: 'Alice', age: 30},
   {name: 'Bob', age: 25},
 ], {
@@ -45,7 +59,7 @@ hux.table([
 });
 
 // Wait indicator
-const stop = hux.wait('Processing...');
+const stop = wait('Processing...');
 // ...do async work...
 stop();
 ```
@@ -53,16 +67,16 @@ stop();
 ### User Interaction
 
 ```js
-import { hux } from '@heroku/heroku-cli-util';
+import { prompt, confirm } from '@heroku/heroku-cli-util/hux';
 
-const name = await hux.prompt('What is your name?');
-const proceed = await hux.confirm('Continue?');
+const name = await prompt('What is your name?');
+const proceed = await confirm('Continue?');
 ```
 
 ### Colors
 
 ```js
-import { color } from '@heroku/heroku-cli-util';
+import * as color from '@heroku/heroku-cli-util/color';
 
 // App-related colors
 console.log(color.app('my-awesome-app'));        // Purple, bold with app icon
@@ -93,21 +107,21 @@ See the [COLORS.md](docs/COLORS.md) documentation for the complete color palette
 #### Error Classes
 
 ```js
-import { utils } from '@heroku/heroku-cli-util';
+import { AmbiguousError, NotFound } from '@heroku/heroku-cli-util/utils';
 
 // Error types
 try {
-  throw new utils.errors.AmbiguousError([{ name: 'foo' }, { name: 'bar' }], 'addon');
+  throw new AmbiguousError([{ name: 'foo' }, { name: 'bar' }], 'addon');
 } catch (err) {
-  if (err instanceof utils.errors.AmbiguousError) {
+  if (err instanceof AmbiguousError) {
     console.error('Ambiguous:', err.message);
   }
 }
 
 try {
-  throw new utils.errors.NotFound();
+  throw new NotFound();
 } catch (err) {
-  if (err instanceof utils.errors.NotFound) {
+  if (err instanceof NotFound) {
     console.error('Not found:', err.message);
   }
 }
@@ -155,16 +169,25 @@ import type {
 ### Database and Utility Helpers
 
 ```js
-import { utils } from '@heroku/heroku-cli-util';
+import { DatabaseResolver, PsqlService, getHost, getPsqlConfigs } from '@heroku/heroku-cli-util/utils/pg';
+import { AddonResolver, isPostgresAddon } from '@heroku/heroku-cli-util/utils/addons';
 
-// Get Heroku Postgres database connection details (requires APIClient from @heroku-cli/command)
-// const db = await utils.pg.databases(herokuApiClient, 'my-app', 'DATABASE_URL');
+// Resolve a database from an app (requires APIClient from @heroku-cli/command)
+const resolver = new DatabaseResolver(herokuApiClient, app, db);
+const database = await resolver.resolve();
 
 // Get Heroku Postgres host
-const host = utils.pg.host();
+const host = getHost();
+
+// Create a PSQL service
+const psql = new PsqlService(database);
+
+// Check if addon is PostgreSQL
+const isPg = isPostgresAddon(addon);
 
-// Run a query (requires a ConnectionDetails object)
-// const result = await utils.pg.psql.exec(db, 'SELECT 1');
+// Resolve an addon
+const addonResolver = new AddonResolver(herokuApiClient, app, addonName);
+const addon = await addonResolver.resolve();
 ```
 
 ## Development

package/dist/index.d.ts

@@ -37,9 +37,8 @@ export declare const utils: {
         NotFound: typeof NotFound;
     };
     pg: {
-        DatabaseResolver: typeof DatabaseResolver;
-        PsqlService: typeof PsqlService;
         addonService: () => string;
+        DatabaseResolver: typeof DatabaseResolver;
         host: typeof getHost;
         isAdvancedDatabase: (addon: DataApiTypes.ExtendedAddon | DataApiTypes.ExtendedAddonAttachment["addon"]) => boolean;
         isAdvancedPrivateDatabase: (addon: DataApiTypes.ExtendedAddon | DataApiTypes.ExtendedAddonAttachment["addon"]) => boolean;
@@ -52,6 +51,7 @@ export declare const utils: {
             getPsqlConfigs: typeof getPsqlConfigs;
             sshTunnel: typeof sshTunnel;
         };
+        PsqlService: typeof PsqlService;
     };
 };
 export declare const hux: {

package/dist/index.js

@@ -10,8 +10,8 @@ import PsqlService from './utils/pg/psql.js';
 import { ago } from './ux/ago.js';
 import { alignColumns } from './ux/align-columns.js';
 import { anykey } from './ux/any-key.js';
-import { confirm } from './ux/confirm.js';
 import { confirmCommand } from './ux/confirm-command.js';
+import { confirm } from './ux/confirm.js';
 import { toHumanReadableDataSize } from './ux/data-size.js';
 import { formatPrice } from './ux/format-price.js';
 import { openUrl } from './ux/open-url.js';
@@ -29,9 +29,8 @@ export const utils = {
         NotFound, // This should be NotFoundError for consistency, but we're keeping it for backwards compatibility
     },
     pg: {
-        DatabaseResolver,
-        PsqlService,
         addonService: getAddonService,
+        DatabaseResolver,
         host: getHost,
         isAdvancedDatabase,
         isAdvancedPrivateDatabase,
@@ -44,6 +43,7 @@ export const utils = {
             getPsqlConfigs,
             sshTunnel,
         },
+        PsqlService,
     },
 };
 export const hux = {

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

@@ -10,44 +10,44 @@ type AddonDescriptor = DeepRequired<Heroku.AddOnAttachment>['addon'];
  * This is the modified type for the `addon` property when the request to Platform API includes the value `addon:plan`
  * in the `Accept-Inclusion` header.
  */
-type AddonDescriptorWithPlanInclusion = {
+type AddonDescriptorWithPlanInclusion = AddonDescriptor & {
     plan: {
         id: string;
         name: string;
     };
-} & AddonDescriptor;
+};
 /**
  * This is the modified type for the `AddOnAttachment` type when the request to Platform API includes the value
  * `config_vars` in the `Accept-Inclusion` header.
  */
-type AddonAttachmentWithConfigVarsInclusion = {
+type AddonAttachmentWithConfigVarsInclusion = DeepRequired<Heroku.AddOnAttachment> & {
     config_vars: string[];
-} & DeepRequired<Heroku.AddOnAttachment>;
+};
 /**
  * This is the modified type for the `AddOnAttachment` we use on these lib functions because all requests made to
  * Platform API to get add-on attachments, either through the Add-on Attachment List endpoint or the
  * add-on attachment resolver action endpoint, include the header `Accept-Inclusion: addon:plan,config_vars`.
  */
-export type ExtendedAddonAttachment = {
+export type ExtendedAddonAttachment = AddonAttachmentWithConfigVarsInclusion & {
     addon: AddonDescriptorWithPlanInclusion;
-} & AddonAttachmentWithConfigVarsInclusion;
+};
 /**
  * This is the modified type for the `AddOn` we use on these lib functions because all requests made to
  * Platform API to get add-ons, either through the Add-on List endpoint or the add-on resolver action endpoint,
  * include the header `Accept-Expansion: addon_service,plan`.
  */
-export type ExtendedAddon = {
+export type ExtendedAddon = DeepRequired<Heroku.AddOn> & {
     addon_service: DeepRequired<Heroku.AddOnService>;
     plan: DeepRequired<Heroku.Plan>;
-} & DeepRequired<Heroku.AddOn>;
+};
 /**
  * The next two types need review and cleanup. They're not used anywhere in this codebase yet.
  */
-export type AddOnWithRelatedData = {
+export type AddOnWithRelatedData = AddonDescriptor & {
     attachment_names?: string[];
     links?: Link[];
     plan: DeepRequired<Heroku.AddOn['plan']>;
-} & AddonDescriptor;
+};
 export type Link = {
     attachment_name?: string;
     created_at: string;

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

@@ -1,6 +1,6 @@
 import { Server } from 'node:net';
 import type { ExtendedAddonAttachment } from './platform-api.js';
-export type ConnectionDetails = {
+export type ConnectionDetails = BastionConfig & {
     _tunnel?: Server;
     attachment?: ExtendedAddonAttachment;
     database: string;
@@ -10,7 +10,7 @@ export type ConnectionDetails = {
     port: string;
     url: string;
     user: string;
-} & BastionConfig;
+};
 export interface TunnelConfig {
     dstHost: string;
     dstPort: number;

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

@@ -0,0 +1,3 @@
+export { default as AddonResolver } from './addon-resolver.js';
+export { default as AttachmentResolver } from './attachment-resolver.js';
+export { getAddonService, isAdvancedDatabase, isAdvancedPrivateDatabase, isEssentialDatabase, isLegacyDatabase, isLegacyEssentialDatabase, isPostgresAddon, } from './helpers.js';

package/dist/utils/addons/index.js

@@ -0,0 +1,3 @@
+export { default as AddonResolver } from './addon-resolver.js';
+export { default as AttachmentResolver } from './attachment-resolver.js';
+export { getAddonService, isAdvancedDatabase, isAdvancedPrivateDatabase, isEssentialDatabase, isLegacyDatabase, isLegacyEssentialDatabase, isPostgresAddon, } from './helpers.js';

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+export { AmbiguousError } from '../errors/ambiguous.js';
+export { NotFound } from '../errors/not-found.js';
+export { default as AddonResolver } from './addons/addon-resolver.js';
+export { getAddonService, isAdvancedDatabase, isAdvancedPrivateDatabase, isEssentialDatabase, isLegacyDatabase, isLegacyEssentialDatabase, isPostgresAddon, } from './addons/helpers.js';
+export { getPsqlConfigs, sshTunnel } from './pg/bastion.js';
+export { getConfigVarNameFromAttachment } from './pg/config-vars.js';
+export { default as DatabaseResolver } from './pg/databases.js';
+export { default as getHost } from './pg/host.js';
+export { default as PsqlService } from './pg/psql.js';

package/dist/utils/index.js

@@ -0,0 +1,9 @@
+export { AmbiguousError } from '../errors/ambiguous.js';
+export { NotFound } from '../errors/not-found.js';
+export { default as AddonResolver } from './addons/addon-resolver.js';
+export { getAddonService, isAdvancedDatabase, isAdvancedPrivateDatabase, isEssentialDatabase, isLegacyDatabase, isLegacyEssentialDatabase, isPostgresAddon, } from './addons/helpers.js';
+export { getPsqlConfigs, sshTunnel } from './pg/bastion.js';
+export { getConfigVarNameFromAttachment } from './pg/config-vars.js';
+export { default as DatabaseResolver } from './pg/databases.js';
+export { default as getHost } from './pg/host.js';
+export { default as PsqlService } from './pg/psql.js';

package/dist/utils/pg/config-vars.d.ts

@@ -1,5 +1,5 @@
-import type { HTTP } from '@heroku/http-call';
 import type { APIClient } from '@heroku-cli/command';
+import type { HTTP } from '@heroku/http-call';
 import type { ExtendedAddonAttachment } from '../../types/pg/platform-api.js';
 /**
  * Cache of app config vars.

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

@@ -25,9 +25,9 @@ export default class DatabaseResolver {
      * @returns Promise resolving to all Heroku Postgres databases
      * @throws {Error} When no legacy database add-on exists on the app
      */
-    getAllLegacyDatabases(app: string): Promise<Array<{
+    getAllLegacyDatabases(app: string): Promise<Array<ExtendedAddonAttachment['addon'] & {
         attachment_names?: string[];
-    } & ExtendedAddonAttachment['addon']>>;
+    }>>;
     /**
      * Resolves an arbitrary legacy database add-on based on the provided app name.
      *

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

@@ -1 +1 @@
-export default function (): string;
+export default function getHost(): string;

package/dist/utils/pg/host.js

@@ -1,4 +1,4 @@
-export default function () {
+export default function getHost() {
     const host = process.env.HEROKU_DATA_HOST || process.env.HEROKU_POSTGRESQL_HOST;
     return host ?? 'api.data.heroku.com';
 }

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

@@ -0,0 +1,5 @@
+export { getPsqlConfigs, sshTunnel } from './bastion.js';
+export { getConfigVarNameFromAttachment } from './config-vars.js';
+export { default as DatabaseResolver } from './databases.js';
+export { default as getHost } from './host.js';
+export { default as PsqlService } from './psql.js';

package/dist/utils/pg/index.js

@@ -0,0 +1,5 @@
+export { getPsqlConfigs, sshTunnel } from './bastion.js';
+export { getConfigVarNameFromAttachment } from './config-vars.js';
+export { default as DatabaseResolver } from './databases.js';
+export { default as getHost } from './host.js';
+export { default as PsqlService } from './psql.js';

package/dist/ux/any-key.js

@@ -14,7 +14,8 @@ function readChar() {
 export async function anykey(message) {
     const { isRaw, isTTY } = process.stdin;
     if (!message) {
-        message = isTTY ? `Press any key to continue or ${color.yellow('q')} to exit`
+        message = isTTY
+            ? `Press any key to continue or ${color.yellow('q')} to exit`
             : `Press enter to continue or ${color.yellow('q')} to exit`;
     }
     if (isTTY)

package/dist/ux/confirm-command.js

@@ -38,19 +38,28 @@ export async function confirmCommand({ abortedMessage, comparison, confirmation,
     if (confirmation) {
         if (confirmation === comparison)
             return;
-        throw new Error(`Confirmation ${color.bold.red(confirmation)} did not match ${color.bold.red(comparison)}. ${abortedMessage}`);
+        throw new Error(`Confirmation ${color.warning(confirmation)} did not match ${color.info(comparison)}. ${abortedMessage}`);
     }
     if (!warningMessage) {
-        warningMessage = heredoc `
+        warningMessage = heredoc(`
       Destructive Action
-      This command will affect the app ${color.bold.red(comparison)}
-    `;
+      This command will affect the app ${color.app(comparison)}
+    `).trimEnd();
     }
     ux.warn(warningMessage);
     process.stderr.write('\n');
-    const entered = await promptFunction(`To proceed, type ${color.bold.red(comparison)} or re-run this command with ${color.bold.red(`--confirm ${comparison}`)}`, { required: true });
-    if (entered === comparison) {
-        return;
+    try {
+        const entered = await promptFunction(`To proceed, type ${color.warning(comparison)} or re-run this command with ${color.code(`--confirm ${comparison}`)}`, { required: true });
+        if (entered === comparison) {
+            return;
+        }
+        throw new Error(`Confirmation did not match ${color.info(comparison)}. ${abortedMessage}`);
+    }
+    catch (error) {
+        const err = error;
+        if (err.name === 'ExitPromptError' && err.message.includes('SIGINT')) {
+            throw new Error(`Cancelled with ${color.warning('CTRL+C')}. ${abortedMessage}`);
+        }
+        throw error;
     }
-    throw new Error(`Confirmation did not match ${color.bold.red(comparison)}. ${abortedMessage}`);
 }

package/dist/ux/index.d.ts

@@ -0,0 +1,16 @@
+export { ago } from './ago.js';
+export { alignColumns } from './align-columns.js';
+export { anykey } from './any-key.js';
+export * as color from './colors.js';
+export { confirmCommand } from './confirm-command.js';
+export { confirm } from './confirm.js';
+export { toHumanReadableDataSize } from './data-size.js';
+export { formatPrice } from './format-price.js';
+export { openUrl } from './open-url.js';
+export { prompt } from './prompt.js';
+export { styledHeader } from './styled-header.js';
+export { styledJSON } from './styled-json.js';
+export { styledObject } from './styled-object.js';
+export { table } from './table.js';
+export { toTitleCase } from './to-title-case.js';
+export { wait } from './wait.js';

package/dist/ux/index.js

@@ -0,0 +1,16 @@
+export { ago } from './ago.js';
+export { alignColumns } from './align-columns.js';
+export { anykey } from './any-key.js';
+export * as color from './colors.js';
+export { confirmCommand } from './confirm-command.js';
+export { confirm } from './confirm.js';
+export { toHumanReadableDataSize } from './data-size.js';
+export { formatPrice } from './format-price.js';
+export { openUrl } from './open-url.js';
+export { prompt } from './prompt.js';
+export { styledHeader } from './styled-header.js';
+export { styledJSON } from './styled-json.js';
+export { styledObject } from './styled-object.js';
+export { table } from './table.js';
+export { toTitleCase } from './to-title-case.js';
+export { wait } from './wait.js';

package/dist/ux/table.d.ts

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

package/dist/ux/table.js

@@ -9,14 +9,16 @@ export function table(data, columns, options) {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { printLine, ...tableOptions } = options || {};
     printTable({
-        ...(tableOptions?.noStyle ? {} : {
-            borderColor: 'whiteBright',
-            borderStyle: 'headers-only-with-underline',
-            headerOptions: {
-                bold: true,
-                color: 'white', // or 'reset' to use default terminal color
-            },
-        }),
+        ...(tableOptions?.noStyle
+            ? {}
+            : {
+                borderColor: 'whiteBright',
+                borderStyle: 'headers-only-with-underline',
+                headerOptions: {
+                    bold: true,
+                    color: 'white', // or 'reset' to use default terminal color
+                },
+            }),
         ...tableOptions,
         columns: cols,
         data: d,

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@heroku/heroku-cli-util",
-  "version": "10.6.1",
+  "version": "10.7.0-beta.0",
   "description": "Set of helpful CLI utilities",
   "author": "Heroku",
   "license": "ISC",
@@ -11,36 +11,71 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./color": {
+      "types": "./dist/ux/colors.d.ts",
+      "import": "./dist/ux/colors.js",
+      "default": "./dist/ux/colors.js"
+    },
+    "./colors": {
+      "types": "./dist/ux/colors.d.ts",
+      "import": "./dist/ux/colors.js",
+      "default": "./dist/ux/colors.js"
+    },
+    "./hux": {
+      "types": "./dist/ux/index.d.ts",
+      "import": "./dist/ux/index.js",
+      "default": "./dist/ux/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js",
+      "default": "./dist/utils/index.js"
+    },
+    "./utils/pg": {
+      "types": "./dist/utils/pg/index.d.ts",
+      "import": "./dist/utils/pg/index.js",
+      "default": "./dist/utils/pg/index.js"
+    },
+    "./utils/addons": {
+      "types": "./dist/utils/addons/index.d.ts",
+      "import": "./dist/utils/addons/index.js",
+      "default": "./dist/utils/addons/index.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "devDependencies": {
     "@heroku-cli/schema": "^2.0.0",
-    "@heroku-cli/test-utils": "^0.1.2",
-    "@types/chai": "^4.3.13",
+    "@heroku-cli/test-utils": "^0.2.0",
+    "@types/chai": "^5.2.3",
     "@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/sinon": "^20.0.0",
     "@types/sinon-chai": "^4.0.0",
     "@types/tmp": "^0.2.6",
     "@types/tunnel-ssh": "4.1.1",
-    "c8": "^7.7.0",
-    "chai": "^4.4.1",
-    "chai-as-promised": "^8.0.1",
+    "c8": "^11.0.0",
+    "chai": "^5.3.3",
+    "chai-as-promised": "^8.0.2",
     "eslint": "^9",
     "eslint-config-oclif": "^6.0.144",
-    "eslint-plugin-mocha": "^11.2.0",
     "mocha": "^11",
     "mock-stdin": "^1.0.0",
-    "nock": "^13.2.9",
+    "nock": "^14.0.11",
     "open": "^11",
-    "sinon": "^18.0.1",
-    "sinon-chai": "^3.7.0",
+    "sinon": "^20.0.0",
+    "sinon-chai": "^4.0.1",
     "tmp": "^0.2.5",
-    "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.4.0"
   },
   "dependencies": {
@@ -63,10 +98,9 @@
     "clean": "rm -rf dist",
     "example": "sh examples/run.sh",
     "lint": "eslint .",
-    "posttest": "npm run lint",
+    "lint:fix": "eslint --fix",
     "prepare": "npm run build",
-    "test": "c8 mocha --forbid-only \"test/**/*.test.ts\"",
-    "test:local": "c8 mocha \"${npm_config_file:-test/**/*.test.+(ts|tsx)}\""
+    "test": "npm run build && c8 --all --check-coverage --reporter=lcov --reporter=text-summary mocha --forbid-only \"test/**/*.test.ts\""
   },
   "overrides": {
     "serialize-javascript": "^7.0.3"