@salesforce/sf-plugins-core 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.2.0](https://github.com/salesforcecli/sf-plugins-core/compare/v1.1.0...v1.2.0) (2022-01-27)
+
+### Features
+
+- expose ux methods in SfCommand ([8e58a93](https://github.com/salesforcecli/sf-plugins-core/commit/8e58a93a942d5a0305a77a82e938f778c59fcd16))
+
 ## [1.1.0](https://github.com/salesforcecli/sf-plugins-core/compare/v1.0.5...v1.1.0) (2022-01-03)
 
 ### Features

package/README.md

@@ -2,4 +2,44 @@
 
 # Description
 
-Utilities for writing [sf](https://github.com/salesforcecli/cli) plugins.
+The @salesforce/sf-pluins-core provides utilities for writing [sf](https://github.com/salesforcecli/cli) plugins.
+
+## SfCommand Abstract Class
+
+The SfCommand abstract class extends [@oclif/core's Command class](https://github.com/oclif/core/blob/main/src/command.ts) for examples of how to build a definition.
+) class and adds useful extensions to ease the development of commands for use in the Salesforce Unified CLI.
+
+- SfCommand takes a generic type that defines the success JSON result
+- Enable the json flag support by default
+- Provides functions that help place success messages, warnings and errors into the correct location in JSON results
+- Enables additional help sections to the standard oclif command help output
+- Provides access to the [cli-ux cli actions](https://github.com/oclif/cli-ux#cliaction) via the public property `spinner` in SfCommand. This avoids having to import that interface from cli-ux.
+
+## Sf Hooks
+
+Interface that defines the well known Unified CLI command hooks.
+SfHooks takes advantage of the [oclif hooks framework](https://oclif.io/docs/hooks), which provides a set of predefined events and the provides ability to define your own.
+
+A hook has a name, say `sf:deploy` and to participate in the hook's run call, one creates a hook consumer, that registers itself using the name `sf:deploy`.
+There can be more than one hook registered with the same name and when the hook is "run", oclif hook will run each registered hook consumer, collect all results and return those results to the caller.
+
+- See [oclif hooks API docs](https://oclif.io/docs/hooks.ts) for a general description of hooks.
+- See [SfHooks](src/hooks.ts) for current hook definitions available in Unified CLI.
+- See Command [Deploy](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/main/src/commands/deploy.ts) for and example of how to run a hook (search for [SfHook](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/main/src/commands/deploy.ts).run in linked file).
+- See [@salesforce/plugin-deploy-retrieve-metadataA#src/hooks/deploy.ts](https://github.com/salesforcecli/plugin-deploy-retrieve-metadata/blob/main/src/hooks/deploy.ts) as an example implementation of a hook consumer.
+
+## Deployer Interface
+
+Interface for deploying Deployables. See [@salesforce/plugin-deploy-retrieve-metadata#src/utils/metadataDeployer.ts](https://github.com/salesforcecli/plugin-deploy-retrieve-metadata/blob/main/src/utils/metadataDeployer.ts) as an example implementation.
+
+## Deauthorizer Abstract Class
+
+The Deauthorizer is an abstract class that is used to implement a concrete implementations of deauthorizing an environment.
+
+## Prompter Class
+
+A general purpose class that prompts a user for information. See [inquirer NPM Module](https://www.npmjs.com/package/inquirer) for more information.
+
+## Flags
+
+Flags is a convenience reference to [@oclif/core#Flags](https://github.com/oclif/core/blob/main/src/flags.ts)

package/lib/deauthorizer.d.ts

@@ -1,4 +1,8 @@
 import { JsonMap } from '@salesforce/ts-types';
+/**
+ * The Deauthorizer is an abstract class that is used to implement a concrete implementations
+ * of deauthorizing an environment.
+ */
 export declare abstract class Deauthorizer<T = JsonMap> {
     removeAll(): Promise<Deauthorizer.Result>;
     /**

package/lib/deauthorizer.js

@@ -1,12 +1,16 @@
 "use strict";
 /*
- * Copyright (c) 2020, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Deauthorizer = void 0;
+/**
+ * The Deauthorizer is an abstract class that is used to implement a concrete implementations
+ * of deauthorizing an environment.
+ */
 class Deauthorizer {
     async removeAll() {
         const result = {

package/lib/deployer.d.ts

@@ -9,12 +9,12 @@ export declare abstract class Deployable {
     abstract getParent(): Deployer;
 }
 /**
- * Interface for deploying Salesforce Org metadata.
+ * Interface for deploying Deployables.
  */
 export declare abstract class Deployer extends EventEmitter {
     /**
      * Deployables are individual pieces that can be deployed on their own. For example,
-     * each pacakge in a salesforce project is considered a deployable that can be deployed
+     * each package in a salesforce project is considered a deployable that can be deployed
      * on its own.
      */
     deployables: Deployable[];

package/lib/deployer.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright (c) 2021, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
@@ -8,24 +8,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Deployer = exports.Deployable = void 0;
 const events_1 = require("events");
-const cli_ux_1 = require("cli-ux");
-const prompter_1 = require("./prompter");
+const core_1 = require("@oclif/core");
+const ux_1 = require("./ux");
 class Deployable {
 }
 exports.Deployable = Deployable;
 /**
- * Interface for deploying Salesforce Org metadata.
+ * Interface for deploying Deployables.
  */
 class Deployer extends events_1.EventEmitter {
     constructor() {
         super(...arguments);
         /**
          * Deployables are individual pieces that can be deployed on their own. For example,
-         * each pacakge in a salesforce project is considered a deployable that can be deployed
+         * each package in a salesforce project is considered a deployable that can be deployed
          * on its own.
          */
         this.deployables = [];
-        this.prompter = new prompter_1.Prompter();
+        this.prompter = new ux_1.Prompter();
     }
     /**
      * Method for displaying deploy progress to the user
@@ -36,7 +36,7 @@ class Deployer extends events_1.EventEmitter {
      * Log messages to the console
      */
     log(msg, ...args) {
-        cli_ux_1.default.log(msg, ...args);
+        core_1.CliUx.ux.log(msg, ...args);
     }
     /**
      * Prompt user for additional information

package/lib/exported.d.ts

@@ -1,7 +1,7 @@
-export { generateTableChoices, toHelpSection } from './util';
+export { toHelpSection } from './util';
 export { Deployable, Deployer } from './deployer';
 export { Deauthorizer } from './deauthorizer';
-export { Prompter } from './prompter';
+export { Progress, Prompter, generateTableChoices } from './ux';
 export { SfHook } from './hooks';
 export * from './types';
 export { SfCommand, SfCommandInterface } from './sfCommand';

package/lib/exported.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright (c) 2021, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
@@ -16,17 +16,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Flags = exports.SfCommand = exports.SfHook = exports.Prompter = exports.Deauthorizer = exports.Deployer = exports.Deployable = exports.toHelpSection = exports.generateTableChoices = void 0;
+exports.Flags = exports.SfCommand = exports.SfHook = exports.generateTableChoices = exports.Prompter = exports.Progress = exports.Deauthorizer = exports.Deployer = exports.Deployable = exports.toHelpSection = void 0;
 var util_1 = require("./util");
-Object.defineProperty(exports, "generateTableChoices", { enumerable: true, get: function () { return util_1.generateTableChoices; } });
 Object.defineProperty(exports, "toHelpSection", { enumerable: true, get: function () { return util_1.toHelpSection; } });
 var deployer_1 = require("./deployer");
 Object.defineProperty(exports, "Deployable", { enumerable: true, get: function () { return deployer_1.Deployable; } });
 Object.defineProperty(exports, "Deployer", { enumerable: true, get: function () { return deployer_1.Deployer; } });
 var deauthorizer_1 = require("./deauthorizer");
 Object.defineProperty(exports, "Deauthorizer", { enumerable: true, get: function () { return deauthorizer_1.Deauthorizer; } });
-var prompter_1 = require("./prompter");
-Object.defineProperty(exports, "Prompter", { enumerable: true, get: function () { return prompter_1.Prompter; } });
+var ux_1 = require("./ux");
+Object.defineProperty(exports, "Progress", { enumerable: true, get: function () { return ux_1.Progress; } });
+Object.defineProperty(exports, "Prompter", { enumerable: true, get: function () { return ux_1.Prompter; } });
+Object.defineProperty(exports, "generateTableChoices", { enumerable: true, get: function () { return ux_1.generateTableChoices; } });
 var hooks_1 = require("./hooks");
 Object.defineProperty(exports, "SfHook", { enumerable: true, get: function () { return hooks_1.SfHook; } });
 __exportStar(require("./types"), exports);

package/lib/hooks.d.ts

@@ -3,6 +3,9 @@ import { Hook, Hooks } from '@oclif/core/lib/interfaces/hooks';
 import { Deployer } from './deployer';
 import { EnvList, EnvDisplay, JsonObject, Deploy, Login, Logout } from './types';
 import { Deauthorizer } from './deauthorizer';
+/**
+ * Interface that defines the well known Unified CLI command hooks.
+ */
 interface SfHooks<T = unknown> extends Hooks {
     'sf:env:list': EnvList.HookMeta<T & JsonObject>;
     'sf:env:display': EnvDisplay.HookMeta<T & JsonObject>;
@@ -11,6 +14,9 @@ interface SfHooks<T = unknown> extends Hooks {
     'sf:logout': Logout.HookMeta<T & Deauthorizer>;
 }
 declare type GenericHook<T extends keyof SfHooks, P> = Hook<T, SfHooks<P>>;
+/**
+ * Class that provides a static method to run a well known hook.
+ */
 export declare class SfHook {
     static run<T extends keyof SfHooks>(config: Config, hookName: T, options?: SfHooks[T]['options']): Promise<Hook.Result<SfHooks[T]['return']>>;
 }

package/lib/hooks.js

@@ -1,21 +1,24 @@
 "use strict";
 /*
- * Copyright (c) 2021, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SfHook = void 0;
-const cli_ux_1 = require("cli-ux");
 const kit_1 = require("@salesforce/kit");
+const core_1 = require("@oclif/core");
+/**
+ * Class that provides a static method to run a well known hook.
+ */
 class SfHook {
     static async run(config, hookName, options = {}) {
         const timeout = kit_1.Duration.milliseconds(kit_1.env.getNumber('SF_HOOK_TIMEOUT_MS') || 5000);
         const results = await config.runHook(hookName, options, timeout.milliseconds);
         results.failures.forEach((failure) => {
-            cli_ux_1.cli.debug(`Failed to run ${hookName} hook for ${failure.plugin.name}`);
-            cli_ux_1.cli.debug(failure.error.toString());
+            core_1.CliUx.ux.debug(`Failed to run ${hookName} hook for ${failure.plugin.name}`);
+            core_1.CliUx.ux.debug(failure.error.toString());
         });
         return results;
     }

package/lib/sfCommand.d.ts

@@ -1,5 +1,6 @@
-import { Command, Config, HelpSection, Interfaces } from '@oclif/core';
-import { Spinner } from './ux';
+import { CliUx, Command, Config, HelpSection, Interfaces } from '@oclif/core';
+import { AnyJson } from '@salesforce/ts-types';
+import { Progress, Prompter, Spinner, Ux } from './ux';
 export interface SfCommandInterface extends Interfaces.Command {
     configurationVariablesSection?: HelpSection;
     envVariablesSection?: HelpSection;
@@ -18,8 +19,12 @@ export declare abstract class SfCommand<T> extends Command {
     static configurationVariablesSection?: HelpSection;
     static envVariablesSection?: HelpSection;
     static errorCodes?: HelpSection;
+    static tableFlags: typeof CliUx.Table.table.flags;
     spinner: Spinner;
+    progress: Progress;
     private warnings;
+    private ux;
+    private prompter;
     constructor(argv: string[], config: Config);
     /**
      * Log warning to users. If --json is enabled, then the warning
@@ -31,6 +36,36 @@ export declare abstract class SfCommand<T> extends Command {
      * logging to the console.
      */
     logSensitive(msg?: string): void;
+    /**
+     * Display a table on the console. Will automatically be suppressed when --json flag is present.
+     */
+    table<R extends Ux.Table.Data>(data: R[], columns: Ux.Table.Columns<R>, options?: Ux.Table.Options): void;
+    /**
+     * Log a stylized url to the console. Will automatically be suppressed when --json flag is present.
+     */
+    url(text: string, uri: string, params?: {}): void;
+    /**
+     * Log stylized JSON to the console. Will automatically be suppressed when --json flag is present.
+     */
+    styledJSON(obj: AnyJson): void;
+    /**
+     * Log stylized object to the console. Will automatically be suppressed when --json flag is present.
+     */
+    styledObject(obj: AnyJson): void;
+    /**
+     * Prompt user for information. See https://www.npmjs.com/package/inquirer for more.
+     *
+     * This will NOT be automatically suppressed when the --json flag is present since we assume
+     * that any command that prompts the user for required information will not also support the --json flag.
+     *
+     * If you need to conditionally suppress prompts to support json output, then do the following:
+     *
+     * @example
+     * if (!this.jsonEnabled()) {
+     *   await this.prompt();
+     * }
+     */
+    prompt<R = Prompter.Answers>(questions: Prompter.Questions<R>, initialAnswers?: Partial<R>): Promise<R>;
     /**
      * Wrap the command result into the standardized JSON structure.
      */

package/lib/sfCommand.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SfCommand = void 0;
 /*
- * Copyright (c) 2021, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
@@ -24,7 +24,11 @@ class SfCommand extends core_1.Command {
     constructor(argv, config) {
         super(argv, config);
         this.warnings = [];
-        this.spinner = new ux_1.Spinner(this.jsonEnabled());
+        const outputEnabled = !this.jsonEnabled();
+        this.spinner = new ux_1.Spinner(outputEnabled);
+        this.progress = new ux_1.Progress(outputEnabled);
+        this.ux = new ux_1.Ux(outputEnabled);
+        this.prompter = new ux_1.Prompter();
     }
     /**
      * Log warning to users. If --json is enabled, then the warning
@@ -43,6 +47,46 @@ class SfCommand extends core_1.Command {
         this.warn(messages.getMessage('warning.security'));
         this.log(msg);
     }
+    /**
+     * Display a table on the console. Will automatically be suppressed when --json flag is present.
+     */
+    table(data, columns, options) {
+        this.ux.table(data, columns, options);
+    }
+    /**
+     * Log a stylized url to the console. Will automatically be suppressed when --json flag is present.
+     */
+    url(text, uri, params = {}) {
+        this.ux.url(text, uri, params);
+    }
+    /**
+     * Log stylized JSON to the console. Will automatically be suppressed when --json flag is present.
+     */
+    styledJSON(obj) {
+        this.ux.styledJSON(obj);
+    }
+    /**
+     * Log stylized object to the console. Will automatically be suppressed when --json flag is present.
+     */
+    styledObject(obj) {
+        this.ux.styledObject(obj);
+    }
+    /**
+     * Prompt user for information. See https://www.npmjs.com/package/inquirer for more.
+     *
+     * This will NOT be automatically suppressed when the --json flag is present since we assume
+     * that any command that prompts the user for required information will not also support the --json flag.
+     *
+     * If you need to conditionally suppress prompts to support json output, then do the following:
+     *
+     * @example
+     * if (!this.jsonEnabled()) {
+     *   await this.prompt();
+     * }
+     */
+    async prompt(questions, initialAnswers) {
+        return this.prompter.prompt(questions, initialAnswers);
+    }
     /**
      * Wrap the command result into the standardized JSON structure.
      */
@@ -70,4 +114,5 @@ class SfCommand extends core_1.Command {
 }
 exports.SfCommand = SfCommand;
 SfCommand.enableJsonFlag = true;
+SfCommand.tableFlags = core_1.CliUx.ux.table.flags;
 //# sourceMappingURL=sfCommand.js.map

package/lib/types/index.d.ts

@@ -46,8 +46,8 @@ export declare namespace EnvDisplay {
 /**
  * By default `sf env list` will render a table with all the data provided by the hook.
  * The columns of the table are derived from the keys of the provided data. These column
- * headers are Title Cased for readability. To overwrite a column name specifiy it the `keys`
- * property.
+ * headers are Title Cased for readability. To overwrite a column name specify it with
+ * the `keys` property.
  *
  * @example
  * {

package/lib/types/index.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright (c) 2020, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
@@ -10,8 +10,8 @@ exports.EnvList = void 0;
 /**
  * By default `sf env list` will render a table with all the data provided by the hook.
  * The columns of the table are derived from the keys of the provided data. These column
- * headers are Title Cased for readability. To overwrite a column name specifiy it the `keys`
- * property.
+ * headers are Title Cased for readability. To overwrite a column name specify it with
+ * the `keys` property.
  *
  * @example
  * {

package/lib/util.d.ts

@@ -1,19 +1,5 @@
-import { ChoiceBase } from 'inquirer';
-import { Dictionary, Nullable } from '@salesforce/ts-types';
 import { HelpSection } from '@oclif/core';
-import { OrgConfigProperties } from '@salesforce/core';
-import { SfdxPropertyKeys } from '@salesforce/core';
-import { EnvironmentVariable } from '@salesforce/core';
-/**
- * Generate a formatted table for list and checkbox prompts
- *
- * Each option should contain the same keys as specified in columns.
- * For example,
- * const columns = { name: 'Name', type: 'Type', path: 'Path' };
- * const options = [{ name: 'foo', type: 'org', path: '/path/to/foo/' }];
- * generateTableChoices(columns, options);
- */
-export declare function generateTableChoices<T>(columns: Dictionary<string>, choices: Array<Dictionary<Nullable<string> | T>>, padForCheckbox?: boolean): ChoiceBase[];
+import { OrgConfigProperties, SfdxPropertyKeys, EnvironmentVariable } from '@salesforce/core';
 /**
  * Function to build a help section for command help.
  * Takes a string to be used as section header text and an array of enums

package/lib/util.js

@@ -1,47 +1,13 @@
 "use strict";
 /*
- * Copyright (c) 2021, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toHelpSection = exports.generateTableChoices = void 0;
-const inquirer_1 = require("inquirer");
-const ts_types_1 = require("@salesforce/ts-types");
+exports.toHelpSection = void 0;
 const core_1 = require("@salesforce/core");
-const core_2 = require("@salesforce/core");
-const core_3 = require("@salesforce/core");
-/**
- * Generate a formatted table for list and checkbox prompts
- *
- * Each option should contain the same keys as specified in columns.
- * For example,
- * const columns = { name: 'Name', type: 'Type', path: 'Path' };
- * const options = [{ name: 'foo', type: 'org', path: '/path/to/foo/' }];
- * generateTableChoices(columns, options);
- */
-function generateTableChoices(columns, choices, 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-padForCheckbox = true) {
-    const columnEntries = Object.entries(columns);
-    const columnLengths = columnEntries.map(([key, value]) => Math.max(ts_types_1.ensureString(value).length, ...choices.map((option) => ts_types_1.ensureString(option[key], `Type ${typeof option[key]} for ${key} in ${Object.keys(option).join(', ')}`)
-        .length)) + 1);
-    const choicesOptions = [
-        new inquirer_1.Separator(`${padForCheckbox ? ' '.repeat(2) : ''}${columnEntries
-            .map(([, value], index) => value === null || value === void 0 ? void 0 : value.padEnd(columnLengths[index], ' '))
-            .join('')}`),
-    ];
-    for (const meta of choices) {
-        const name = columnEntries
-            .map(([key], index) => ts_types_1.ensureString(meta[key]).padEnd(columnLengths[index], ' '))
-            .join('');
-        const choice = { name, value: meta.value, short: ts_types_1.ensureString(meta.name) };
-        choicesOptions.push(choice);
-    }
-    return choicesOptions;
-}
-exports.generateTableChoices = generateTableChoices;
 /**
  * Function to build a help section for command help.
  * Takes a string to be used as section header text and an array of enums
@@ -60,11 +26,11 @@ function toHelpSection(header, ...vars) {
         if (orgConfig) {
             return { name: orgConfig.key, description: orgConfig.description };
         }
-        const sfdxProperty = core_2.SFDX_ALLOWED_PROPERTIES.find(({ key }) => key === v);
+        const sfdxProperty = core_1.SFDX_ALLOWED_PROPERTIES.find(({ key }) => key === v);
         if (sfdxProperty) {
             return { name: sfdxProperty.key.valueOf(), description: sfdxProperty.description };
         }
-        const envVar = Object.entries(core_3.SUPPORTED_ENV_VARS).find(([k]) => k === v);
+        const envVar = Object.entries(core_1.SUPPORTED_ENV_VARS).find(([k]) => k === v);
         if (envVar) {
             const [eKey, data] = envVar;
             return { name: eKey, description: data.description };

package/lib/ux/base.d.ts

@@ -0,0 +1,6 @@
+import { AnyFunction } from '@salesforce/ts-types';
+export declare class UxBase {
+    protected outputEnabled: boolean;
+    constructor(outputEnabled: boolean);
+    protected maybeNoop(fn: AnyFunction<unknown>): void;
+}

package/lib/ux/base.js

@@ -0,0 +1,20 @@
+"use strict";
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UxBase = void 0;
+class UxBase {
+    constructor(outputEnabled) {
+        this.outputEnabled = outputEnabled;
+    }
+    maybeNoop(fn) {
+        if (this.outputEnabled)
+            fn();
+    }
+}
+exports.UxBase = UxBase;
+//# sourceMappingURL=base.js.map

package/lib/ux/index.d.ts

@@ -0,0 +1,5 @@
+export { UxBase } from './base';
+export { Ux } from './ux';
+export { Progress } from './progress';
+export { Prompter, generateTableChoices } from './prompter';
+export { Spinner } from './spinner';

package/lib/ux/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Spinner = exports.generateTableChoices = exports.Prompter = exports.Progress = exports.Ux = exports.UxBase = void 0;
+var base_1 = require("./base");
+Object.defineProperty(exports, "UxBase", { enumerable: true, get: function () { return base_1.UxBase; } });
+var ux_1 = require("./ux");
+Object.defineProperty(exports, "Ux", { enumerable: true, get: function () { return ux_1.Ux; } });
+var progress_1 = require("./progress");
+Object.defineProperty(exports, "Progress", { enumerable: true, get: function () { return progress_1.Progress; } });
+var prompter_1 = require("./prompter");
+Object.defineProperty(exports, "Prompter", { enumerable: true, get: function () { return prompter_1.Prompter; } });
+Object.defineProperty(exports, "generateTableChoices", { enumerable: true, get: function () { return prompter_1.generateTableChoices; } });
+var spinner_1 = require("./spinner");
+Object.defineProperty(exports, "Spinner", { enumerable: true, get: function () { return spinner_1.Spinner; } });
+//# sourceMappingURL=index.js.map

package/lib/ux/progress.d.ts

@@ -0,0 +1,48 @@
+import { UxBase } from '.';
+/**
+ * Class for display a progress bar to the console. Will automatically be suppressed if the --json flag is present.
+ */
+export declare class Progress extends UxBase {
+    private static DEFAULT_OPTIONS;
+    private bar;
+    private total;
+    constructor(outputEnabled: boolean);
+    /**
+     * Set the total number of expected components.
+     */
+    setTotal(total: number): void;
+    /**
+     * Start the progress bar.
+     */
+    start(total: number, payload?: Progress.Payload, options?: Partial<Progress.Options>): void;
+    /**
+     * Update the progress bar.
+     */
+    update(num: number, payload?: {}): void;
+    /**
+     * Update the progress bar with the final number and stop it.
+     */
+    finish(payload?: {}): void;
+    /**
+     * Stop the progress bar.
+     */
+    stop(): void;
+    private _start;
+}
+export declare namespace Progress {
+    type Bar = {
+        start: (num: number, payload?: unknown) => void;
+        update: (num: number, payload?: unknown) => void;
+        updateTotal: (num: number) => void;
+        setTotal: (num: number) => void;
+        stop: () => void;
+    };
+    type Options = {
+        title: string;
+        format: string;
+        barCompleteChar: string;
+        barIncompleteChar: string;
+        linewrap: boolean;
+    };
+    type Payload = Record<string, unknown>;
+}

package/lib/ux/progress.js

@@ -0,0 +1,83 @@
+"use strict";
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Progress = void 0;
+const util = require("util");
+const core_1 = require("@oclif/core");
+const kit_1 = require("@salesforce/kit");
+const _1 = require(".");
+/**
+ * Class for display a progress bar to the console. Will automatically be suppressed if the --json flag is present.
+ */
+class Progress extends _1.UxBase {
+    constructor(outputEnabled) {
+        super(outputEnabled);
+    }
+    /**
+     * Set the total number of expected components.
+     */
+    setTotal(total) {
+        this.total = total;
+        this.bar.setTotal(total);
+    }
+    /**
+     * Start the progress bar.
+     */
+    start(total, payload = {}, options = Progress.DEFAULT_OPTIONS) {
+        const opts = Object.assign(Progress.DEFAULT_OPTIONS, options);
+        opts.format = util.format(opts.format, opts.title);
+        this.bar = core_1.CliUx.ux.progress({
+            format: opts.format,
+            barCompleteChar: opts.barCompleteChar,
+            barIncompleteChar: opts.barIncompleteChar,
+            linewrap: opts.linewrap,
+        });
+        this.bar.setTotal(total);
+        // this.maybeNoop(() => startProgressBar(this.bar, total, payload));
+        this.maybeNoop(() => {
+            this._start(total, payload);
+        });
+    }
+    /**
+     * Update the progress bar.
+     */
+    update(num, payload = {}) {
+        this.bar.update(num, payload);
+    }
+    /**
+     * Update the progress bar with the final number and stop it.
+     */
+    finish(payload = {}) {
+        this.bar.update(this.total, payload);
+        this.bar.stop();
+    }
+    /**
+     * Stop the progress bar.
+     */
+    stop() {
+        this.bar.stop();
+    }
+    _start(total, payload = {}) {
+        const start = kit_1.once((bar, t, p = {}) => {
+            bar.start(t);
+            if (Object.keys(p).length) {
+                bar.update(0, p);
+            }
+        });
+        start(this.bar, total, payload);
+    }
+}
+exports.Progress = Progress;
+Progress.DEFAULT_OPTIONS = {
+    title: 'PROGRESS',
+    format: '%s | {bar} | {value}/{total} Components',
+    barCompleteChar: '\u2588',
+    barIncompleteChar: '\u2591',
+    linewrap: true,
+};
+//# sourceMappingURL=progress.js.map

package/lib/ux/prompter.d.ts

@@ -0,0 +1,22 @@
+import { QuestionCollection, ChoiceBase } from 'inquirer';
+import { Dictionary, Nullable } from '@salesforce/ts-types';
+export declare class Prompter {
+    /**
+     * Prompt user for information. See https://www.npmjs.com/package/inquirer for more.
+     */
+    prompt<T = Prompter.Answers>(questions: Prompter.Questions<T>, initialAnswers?: Partial<T>): Promise<T>;
+}
+export declare namespace Prompter {
+    type Answers<T = Record<string, unknown>> = T & Record<string, unknown>;
+    type Questions<T> = QuestionCollection<T>;
+}
+/**
+ * Generate a formatted table for list and checkbox prompts
+ *
+ * Each option should contain the same keys as specified in columns.
+ * For example,
+ * const columns = { name: 'Name', type: 'Type', path: 'Path' };
+ * const options = [{ name: 'foo', type: 'org', path: '/path/to/foo/' }];
+ * generateTableChoices(columns, options);
+ */
+export declare function generateTableChoices<T>(columns: Dictionary<string>, choices: Array<Dictionary<Nullable<string> | T>>, padForCheckbox?: boolean): ChoiceBase[];

package/lib/ux/prompter.js

@@ -0,0 +1,52 @@
+"use strict";
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTableChoices = exports.Prompter = void 0;
+const inquirer_1 = require("inquirer");
+const ts_types_1 = require("@salesforce/ts-types");
+class Prompter {
+    /**
+     * Prompt user for information. See https://www.npmjs.com/package/inquirer for more.
+     */
+    async prompt(questions, initialAnswers) {
+        const answers = await inquirer_1.prompt(questions, initialAnswers);
+        return answers;
+    }
+}
+exports.Prompter = Prompter;
+/**
+ * Generate a formatted table for list and checkbox prompts
+ *
+ * Each option should contain the same keys as specified in columns.
+ * For example,
+ * const columns = { name: 'Name', type: 'Type', path: 'Path' };
+ * const options = [{ name: 'foo', type: 'org', path: '/path/to/foo/' }];
+ * generateTableChoices(columns, options);
+ */
+function generateTableChoices(columns, choices, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+padForCheckbox = true) {
+    const columnEntries = Object.entries(columns);
+    const columnLengths = columnEntries.map(([key, value]) => Math.max(ts_types_1.ensureString(value).length, ...choices.map((option) => ts_types_1.ensureString(option[key], `Type ${typeof option[key]} for ${key} in ${Object.keys(option).join(', ')}`)
+        .length)) + 1);
+    const choicesOptions = [
+        new inquirer_1.Separator(`${padForCheckbox ? ' '.repeat(2) : ''}${columnEntries
+            .map(([, value], index) => value === null || value === void 0 ? void 0 : value.padEnd(columnLengths[index], ' '))
+            .join('')}`),
+    ];
+    for (const meta of choices) {
+        const name = columnEntries
+            .map(([key], index) => ts_types_1.ensureString(meta[key]).padEnd(columnLengths[index], ' '))
+            .join('');
+        const choice = { name, value: meta.value, short: ts_types_1.ensureString(meta.name) };
+        choicesOptions.push(choice);
+    }
+    return choicesOptions;
+}
+exports.generateTableChoices = generateTableChoices;
+//# sourceMappingURL=prompter.js.map

package/lib/{ux.d.ts → ux/spinner.d.ts}

@@ -1,10 +1,10 @@
+import { UxBase } from '.';
 /**
- * This class is a light wrapper around cli.action that allows us to
+ * This class is a light wrapper around CliUx.ux.action that allows us to
  * automatically suppress any actions if `--json` flag is present.
  */
-export declare class Spinner {
-    private jsonEnabled;
-    constructor(jsonEnabled: boolean);
+export declare class Spinner extends UxBase {
+    constructor(outputEnabled: boolean);
     /**
      * Start a spinner on the console.
      */

package/lib/{ux.js → ux/spinner.js}

@@ -1,55 +1,52 @@
 "use strict";
 /*
- * Copyright (c) 2021, salesforce.com, inc.
+ * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Spinner = void 0;
-const cli_ux_1 = require("cli-ux");
+const core_1 = require("@oclif/core");
+const _1 = require(".");
 /**
- * This class is a light wrapper around cli.action that allows us to
+ * This class is a light wrapper around CliUx.ux.action that allows us to
  * automatically suppress any actions if `--json` flag is present.
  */
-class Spinner {
-    constructor(jsonEnabled) {
-        this.jsonEnabled = jsonEnabled;
+class Spinner extends _1.UxBase {
+    constructor(outputEnabled) {
+        super(outputEnabled);
     }
     /**
      * Start a spinner on the console.
      */
     start(action, status, opts) {
-        if (!this.jsonEnabled)
-            cli_ux_1.cli.action.start(action, status, opts);
+        this.maybeNoop(() => core_1.CliUx.ux.action.start(action, status, opts));
     }
     /**
      * Stop the spinner on the console.
      */
     stop(msg) {
-        if (!this.jsonEnabled)
-            cli_ux_1.cli.action.stop(msg);
+        this.maybeNoop(() => core_1.CliUx.ux.action.stop(msg));
     }
     /**
      * Set the status of the current spinner.
      */
     set status(status) {
-        if (!this.jsonEnabled)
-            cli_ux_1.cli.action.status = status;
+        core_1.CliUx.ux.action.status = status;
     }
     /**
      * Get the status of the current spinner.
      */
     get status() {
-        return cli_ux_1.cli.action.status;
+        return core_1.CliUx.ux.action.status;
     }
     /**
      * Pause the spinner on the console.
      */
     pause(fn, icon) {
-        if (!this.jsonEnabled)
-            cli_ux_1.cli.action.pause(fn, icon);
+        this.maybeNoop(() => core_1.CliUx.ux.action.pause(fn, icon));
     }
 }
 exports.Spinner = Spinner;
-//# sourceMappingURL=ux.js.map
+//# sourceMappingURL=spinner.js.map

package/lib/ux/ux.d.ts

@@ -0,0 +1,17 @@
+import { CliUx } from '@oclif/core';
+import { AnyJson } from '@salesforce/ts-types';
+import { UxBase } from './base';
+export declare class Ux extends UxBase {
+    constructor(outputEnabled: boolean);
+    table<T extends Ux.Table.Data>(data: T[], columns: Ux.Table.Columns<T>, options?: Ux.Table.Options): void;
+    url(text: string, uri: string, params?: {}): void;
+    styledJSON(obj: AnyJson): void;
+    styledObject(obj: AnyJson): void;
+}
+export declare namespace Ux {
+    namespace Table {
+        type Data = Record<string, unknown>;
+        type Columns<T extends Data> = CliUx.Table.table.Columns<T>;
+        type Options = CliUx.Table.table.Options;
+    }
+}

package/lib/ux/ux.js

@@ -0,0 +1,30 @@
+"use strict";
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ux = void 0;
+const core_1 = require("@oclif/core");
+const base_1 = require("./base");
+class Ux extends base_1.UxBase {
+    constructor(outputEnabled) {
+        super(outputEnabled);
+    }
+    table(data, columns, options) {
+        this.maybeNoop(() => core_1.CliUx.ux.table(data, columns, options));
+    }
+    url(text, uri, params = {}) {
+        this.maybeNoop(() => core_1.CliUx.ux.url(text, uri, params));
+    }
+    styledJSON(obj) {
+        this.maybeNoop(() => core_1.CliUx.ux.styledJSON(obj));
+    }
+    styledObject(obj) {
+        this.maybeNoop(() => core_1.CliUx.ux.styledObject(obj));
+    }
+}
+exports.Ux = Ux;
+//# sourceMappingURL=ux.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sf-plugins-core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Utils for writing deploy and retrieve plugins",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -32,11 +32,10 @@
     "/messages"
   ],
   "dependencies": {
-    "@oclif/core": "^1.0.10",
-    "@salesforce/core": "3.6.6",
+    "@oclif/core": "^1.2.0",
+    "@salesforce/core": "3.7.3",
     "@salesforce/kit": "^1.5.17",
     "@salesforce/ts-types": "^1.5.20",
-    "cli-ux": "^6.0.6",
     "inquirer": "^8.2.0"
   },
   "devDependencies": {
@@ -62,7 +61,7 @@
     "nyc": "^15.1.0",
     "prettier": "^2.0.5",
     "pretty-quick": "^3.1.0",
-    "shelljs": "0.8.1",
+    "shelljs": "0.8.5",
     "sinon": "10.0.0",
     "strip-ansi": "6.0.0",
     "ts-node": "^10.4.0",

package/lib/prompter.d.ts

@@ -1,10 +0,0 @@
-import { QuestionCollection } from 'inquirer';
-export declare class Prompter {
-    /**
-     * Prompt user for information. See https://www.npmjs.com/package/inquirer for more.
-     */
-    prompt<T = Prompter.Answers>(questions: QuestionCollection<T>, initialAnswers?: Partial<T>): Promise<T>;
-}
-export declare namespace Prompter {
-    type Answers<T = Record<string, unknown>> = T & Record<string, unknown>;
-}

package/lib/prompter.js

@@ -1,21 +0,0 @@
-"use strict";
-/*
- * Copyright (c) 2021, salesforce.com, inc.
- * All rights reserved.
- * Licensed under the BSD 3-Clause license.
- * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Prompter = void 0;
-const inquirer_1 = require("inquirer");
-class Prompter {
-    /**
-     * Prompt user for information. See https://www.npmjs.com/package/inquirer for more.
-     */
-    async prompt(questions, initialAnswers) {
-        const answers = await inquirer_1.prompt(questions, initialAnswers);
-        return answers;
-    }
-}
-exports.Prompter = Prompter;
-//# sourceMappingURL=prompter.js.map