@heroku/heroku-cli-util 9.0.2 → 9.1.1

package/dist/errors/ambiguous.d.ts

@@ -0,0 +1,16 @@
+import type { ExtendedAddonAttachment } from '../types/pg/data-api';
+/**
+ * This error is used internally to signal when the `AddonAttachmentResolver` cannot resolve
+ * to a single attachment.
+ */
+export declare class AmbiguousError extends Error {
+    readonly matches: ExtendedAddonAttachment[];
+    readonly type: string;
+    readonly body: {
+        id: string;
+        message: string;
+    };
+    readonly message: string;
+    readonly statusCode = 422;
+    constructor(matches: ExtendedAddonAttachment[], type: string);
+}

package/dist/{types/errors → errors}/ambiguous.js

@@ -1,14 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AmbiguousError = void 0;
+/**
+ * This error is used internally to signal when the `AddonAttachmentResolver` cannot resolve
+ * to a single attachment.
+ */
 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(', ')}.`;
+        this.body = { id: 'multiple_matches', message: this.message };
     }
 }
 exports.AmbiguousError = AmbiguousError;

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

@@ -0,0 +1,20 @@
+/**
+ * This error is used only when the Platform API add-on attachment resolver resolves to one or more matches, but
+ * a namespace (credential name) was provided and none of them had that exact namespace.
+ *
+ * We would've expected this to use the same error message the resolver returns when it throws a Not Found error:
+ * `"Couldn't find that add on attachment."`, because it's attachments and not add-ons that are being resolved.
+ *
+ * However, that's not the case here and we cannot refactor this to use the expected messaging because the only
+ * command checking credentials, `pg:psql`, has a check with a strict match on the error message text to change
+ * the error displayed to the user
+ * ([see here](https://github.com/heroku/cli/blob/b79f2c93d6f21eafd9d93983bcd377e4bc7f8438/packages/cli/src/commands/pg/psql.ts#L32)).
+ */
+export declare class NotFound extends Error {
+    readonly body: {
+        id: string;
+        message: string;
+    };
+    readonly message = "Couldn't find that addon.";
+    readonly statusCode = 404;
+}

package/dist/errors/not-found.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotFound = void 0;
+/**
+ * This error is used only when the Platform API add-on attachment resolver resolves to one or more matches, but
+ * a namespace (credential name) was provided and none of them had that exact namespace.
+ *
+ * We would've expected this to use the same error message the resolver returns when it throws a Not Found error:
+ * `"Couldn't find that add on attachment."`, because it's attachments and not add-ons that are being resolved.
+ *
+ * However, that's not the case here and we cannot refactor this to use the expected messaging because the only
+ * command checking credentials, `pg:psql`, has a check with a strict match on the error message text to change
+ * the error displayed to the user
+ * ([see here](https://github.com/heroku/cli/blob/b79f2c93d6f21eafd9d93983bcd377e4bc7f8438/packages/cli/src/commands/pg/psql.ts#L32)).
+ */
+class NotFound extends Error {
+    constructor() {
+        super(...arguments);
+        this.body = { id: 'not_found', message: 'Couldn\'t find that addon.' };
+        this.message = 'Couldn\'t find that addon.';
+        this.statusCode = 404;
+    }
+}
+exports.NotFound = NotFound;

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-import { AmbiguousError } from './types/errors/ambiguous';
-import { NotFound } from './types/errors/not-found';
-import { AddOnAttachmentWithConfigVarsAndPlan, AddOnWithRelatedData, Link } from './types/pg/data-api';
+import { APIClient } from '@heroku-cli/command';
+import { AmbiguousError } from './errors/ambiguous';
+import { NotFound } from './errors/not-found';
+import { AddOnWithRelatedData, ExtendedAddonAttachment, 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';
@@ -12,26 +11,31 @@ import { styledJSON } from './ux/styled-json';
 import { styledObject } from './ux/styled-object';
 import { table } from './ux/table';
 import { wait } from './ux/wait';
+export type { AddOnWithRelatedData, ExtendedAddonAttachment, Link, } from './types/pg/data-api';
+export type { ConnectionDetails, ConnectionDetailsWithAttachment, TunnelConfig, } from './types/pg/tunnel';
+/** @deprecated Use direct type imports instead */
 export declare const types: {
-    errors: {
-        AmbiguousError: typeof AmbiguousError;
-        NotFound: typeof NotFound;
-    };
     pg: {
-        AddOnAttachmentWithConfigVarsAndPlan: AddOnAttachmentWithConfigVarsAndPlan;
         AddOnWithRelatedData: AddOnWithRelatedData;
         ConnectionDetails: ConnectionDetails;
         ConnectionDetailsWithAttachment: ConnectionDetailsWithAttachment;
+        ExtendedAddonAttachment: ExtendedAddonAttachment;
         Link: Link;
         TunnelConfig: TunnelConfig;
     };
 };
 export declare const utils: {
+    errors: {
+        AmbiguousError: typeof AmbiguousError;
+        NotFound: typeof NotFound;
+    };
     pg: {
-        databases: typeof getDatabase;
+        fetcher: {
+            database(heroku: APIClient, appId: string, attachmentId?: string, namespace?: string): Promise<ConnectionDetailsWithAttachment>;
+        };
         host: typeof getHost;
         psql: {
-            exec: typeof exec;
+            exec(connectionDetails: ConnectionDetailsWithAttachment, query: string, psqlCmdArgs?: string[]): Promise<string>;
         };
     };
 };

package/dist/index.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hux = exports.utils = exports.types = void 0;
-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 tslib_1 = require("tslib");
+const ambiguous_1 = require("./errors/ambiguous");
+const not_found_1 = require("./errors/not-found");
+const databases_1 = tslib_1.__importDefault(require("./utils/pg/databases"));
+const host_1 = tslib_1.__importDefault(require("./utils/pg/host"));
+const psql_1 = tslib_1.__importDefault(require("./utils/pg/psql"));
 const confirm_1 = require("./ux/confirm");
 const prompt_1 = require("./ux/prompt");
 const styled_header_1 = require("./ux/styled-header");
@@ -13,26 +14,36 @@ const styled_json_1 = require("./ux/styled-json");
 const styled_object_1 = require("./ux/styled-object");
 const table_1 = require("./ux/table");
 const wait_1 = require("./ux/wait");
+// Keep const types for backward compatibility (deprecated)
+/** @deprecated Use direct type imports instead */
 exports.types = {
-    errors: {
-        AmbiguousError: ambiguous_1.AmbiguousError,
-        NotFound: not_found_1.NotFound,
-    },
     pg: {
-        AddOnAttachmentWithConfigVarsAndPlan: {},
         AddOnWithRelatedData: {},
         ConnectionDetails: {},
         ConnectionDetailsWithAttachment: {},
+        ExtendedAddonAttachment: {},
         Link: {},
         TunnelConfig: {},
     },
 };
 exports.utils = {
+    errors: {
+        AmbiguousError: ambiguous_1.AmbiguousError,
+        NotFound: not_found_1.NotFound, // This should be NotFoundError for consistency, but we're keeping it for backwards compatibility
+    },
     pg: {
-        databases: databases_1.getDatabase,
+        fetcher: {
+            database(heroku, appId, attachmentId, namespace) {
+                const databaseResolver = new databases_1.default(heroku);
+                return databaseResolver.getDatabase(appId, attachmentId, namespace);
+            },
+        },
         host: host_1.default,
         psql: {
-            exec: psql_1.exec,
+            exec(connectionDetails, query, psqlCmdArgs = []) {
+                const psqlService = new psql_1.default(connectionDetails);
+                return psqlService.execQuery(query, psqlCmdArgs);
+            },
         },
     },
 };

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

@@ -1,13 +1,41 @@
 import * as Heroku from '@heroku-cli/schema';
+type DeepRequired<T> = T extends object ? {
+    [K in keyof T]-?: DeepRequired<T[K]>;
+} : T;
+/**
+ * This is the base type for the property `addon` on an `AddOnAttachment` as described in the Platform API Reference.
+ */
+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 = {
+    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 = {
+    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 = {
+    addon: AddonDescriptorWithPlanInclusion;
+} & AddonAttachmentWithConfigVarsInclusion;
 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>;
+    plan: DeepRequired<Heroku.AddOn['plan']>;
+} & AddonDescriptor;
 export type Link = {
     attachment_name?: string;
     created_at: string;
@@ -15,3 +43,4 @@ export type Link = {
     name: string;
     remote?: Link;
 };
+export {};

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

@@ -1,11 +1,7 @@
-import type { AddOnAttachment } from '@heroku-cli/schema';
 import { Server } from 'node:net';
-import * as createTunnel from 'tunnel-ssh';
-import type { AddOnAttachmentWithConfigVarsAndPlan } from './data-api';
+import type { ExtendedAddonAttachment } from './data-api';
 export type ConnectionDetails = {
     _tunnel?: Server;
-    bastionHost?: string;
-    bastionKey?: string;
     database: string;
     host: string;
     password: string;
@@ -13,10 +9,24 @@ export type ConnectionDetails = {
     port: string;
     url: string;
     user: string;
-};
+} & BastionConfig;
 export type ConnectionDetailsWithAttachment = {
-    attachment: Required<{
-        addon: AddOnAttachmentWithConfigVarsAndPlan;
-    } & AddOnAttachment>;
+    attachment: ExtendedAddonAttachment;
 } & ConnectionDetails;
-export type TunnelConfig = createTunnel.Config;
+export interface TunnelConfig {
+    dstHost: string;
+    dstPort: number;
+    host?: string;
+    localHost: string;
+    localPort: number;
+    privateKey?: string;
+    username: string;
+}
+export interface BastionConfigResponse {
+    host: string;
+    private_key: string;
+}
+export type BastionConfig = {
+    bastionHost?: string;
+    bastionKey?: string;
+};

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

@@ -1,9 +1,13 @@
 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;
+import type { ExtendedAddonAttachment } from '../../types/pg/data-api';
+export interface AddonAttachmentResolverOptions {
+    addonService?: string;
     namespace?: string;
-}) => Promise<{
-    addon: AddOnAttachmentWithConfigVarsAndPlan;
-} & AddOnAttachment>;
+}
+export default class AddonAttachmentResolver {
+    private readonly heroku;
+    private readonly attachmentHeaders;
+    constructor(heroku: APIClient);
+    resolve(appId: string | undefined, attachmentId: string, options?: AddonAttachmentResolverOptions): Promise<ExtendedAddonAttachment>;
+    private singularize;
+}

package/dist/utils/addons/resolve.js

@@ -1,28 +1,34 @@
 "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) => {
+const ambiguous_1 = require("../../errors/ambiguous");
+const not_found_1 = require("../../errors/not-found");
+class AddonAttachmentResolver {
+    constructor(heroku) {
+        this.heroku = heroku;
+        this.attachmentHeaders = {
+            Accept: 'application/vnd.heroku+json; version=3.sdk',
+            'Accept-Inclusion': 'addon:plan,config_vars',
+        };
+    }
+    async resolve(appId, attachmentId, options = {}) {
+        const { body: attachments } = await this.heroku.post('/actions/addon-attachments/resolve', {
+            // eslint-disable-next-line camelcase
+            body: { addon_attachment: attachmentId, addon_service: options.addonService, app: appId },
+            headers: this.attachmentHeaders,
+        });
+        return this.singularize(attachments, options.namespace);
+    }
+    singularize(attachments, namespace) {
+        let matches;
         if (namespace) {
-            matches = matches.filter(m => m.namespace === namespace);
+            matches = attachments.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);
+        else if (attachments.length > 1) {
+            // In cases that aren't specific enough, keep only attachments without a namespace
+            matches = attachments.filter(m => !Reflect.has(m, 'namespace') || m.namespace === null);
+        }
+        else {
+            matches = attachments;
         }
         switch (matches.length) {
             case 0: {
@@ -32,8 +38,9 @@ function singularize(type, namespace) {
                 return matches[0];
             }
             default: {
-                throw new ambiguous_1.AmbiguousError(matches, type !== null && type !== void 0 ? type : '');
+                throw new ambiguous_1.AmbiguousError(matches, 'addon_attachment');
             }
         }
-    };
+    }
 }
+exports.default = AddonAttachmentResolver;

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

@@ -1,30 +1,71 @@
 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): {
+import { Server } from 'node:net';
+import { ExtendedAddonAttachment } from '../../types/pg/data-api';
+import { BastionConfig, ConnectionDetailsWithAttachment, TunnelConfig } from '../../types/pg/tunnel';
+/**
+ * Determines whether the attachment belongs to an add-on installed onto a non-shield Private Space.
+ * If true, the bastion information needs to be fetched from the Data API.
+ * For add-ons installed onto a Shield Private Space, the bastion information should be fetched from config vars.
+ *
+ * @param attachment - The add-on attachment to check
+ * @returns True if the attachment belongs to a non-shield Private Space, false otherwise
+ */
+export declare function bastionKeyPlan(attachment: ExtendedAddonAttachment): boolean;
+/**
+ * Fetches the bastion configuration from the Data API (only relevant for add-ons installed onto a
+ * non-shield Private Space).
+ * For add-ons installed onto a Shield Private Space, the bastion information is stored in the config vars.
+ *
+ * @param heroku - The Heroku API client
+ * @param addon - The add-on information
+ * @returns Promise that resolves to the bastion configuration
+ */
+export declare function fetchBastionConfig(heroku: APIClient, addon: ExtendedAddonAttachment['addon']): Promise<BastionConfig>;
+/**
+ * Returns the bastion configuration from the config vars for add-ons installed onto Shield
+ * Private Spaces.
+ *
+ * If there are bastions, extracts a host and a key from the config vars.
+ * If there are no bastions, returns an empty Object.
+ *
+ * We assert that _BASTIONS and _BASTION_KEY always exist together.
+ * If either is falsy, pretend neither exist.
+ *
+ * @param config - The configuration variables object
+ * @param baseName - The base name for the configuration variables
+ * @returns The bastion configuration object
+ */
+export declare const getBastionConfig: (config: Record<string, string>, baseName: string) => BastionConfig;
+/**
+ * Returns both the required environment variables to effect the psql command execution and the tunnel
+ * configuration according to the database connection details.
+ *
+ * @param connectionDetails - The database connection details with attachment information
+ * @returns Object containing database environment variables and tunnel configuration
+ */
+export declare function getPsqlConfigs(connectionDetails: ConnectionDetailsWithAttachment): {
     dbEnv: NodeJS.ProcessEnv;
-    dbTunnelConfig: createTunnel.Config;
+    dbTunnelConfig: TunnelConfig;
 };
-export declare function sshTunnel(db: ConnectionDetails, dbTunnelConfig: TunnelConfig, timeout?: number): Promise<void | import("net").Server | null>;
-export declare function tunnelConfig(db: ConnectionDetails): TunnelConfig;
+export type PsqlConfigs = ReturnType<typeof getPsqlConfigs>;
+/**
+ * Establishes an SSH tunnel to the database using the provided configuration.
+ *
+ * @param connectionDetails - The database connection details with attachment information
+ * @param dbTunnelConfig - The tunnel configuration object
+ * @param timeout - The timeout in milliseconds (default: 10000)
+ * @param createSSHTunnel - The function to create the SSH tunnel
+ * @returns Promise that resolves to the tunnel server or null if no bastion key is provided
+ * @throws Error if unable to establish the tunnel
+ */
+export declare function sshTunnel(connectionDetails: ConnectionDetailsWithAttachment, dbTunnelConfig: TunnelConfig, timeout?: number, createSSHTunnel?: typeof createSSHTunnelAdapter): Promise<Server | void>;
+/**
+ * Adapter for tunnel-ssh v5 API. Translates our TunnelConfig into the v5
+ * createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions) call
+ * and returns the created local Server.
+ *
+ * @param config - The tunnel configuration to translate for v5 API
+ * @returns Promise that resolves to the created local TCP Server
+ */
+declare function createSSHTunnelAdapter(config: TunnelConfig): Promise<Server>;
+export {};