@salesforce/sf-plugins-core 1.15.1 → 1.16.0

package/lib/exported.d.ts

@@ -3,7 +3,7 @@ import { Flags as OclifFlags } from '@oclif/core';
 export { toHelpSection, parseVarArgs } from './util';
 export { Deployable, Deployer, DeployerResult } from './deployer';
 export { Deauthorizer } from './deauthorizer';
-export { Progress, Prompter, generateTableChoices } from './ux';
+export { Progress, Prompter, generateTableChoices, Ux } from './ux';
 export { SfHook } from './hooks';
 export * from './types';
 export { SfCommand, SfCommandInterface, StandardColors } from './sfCommand';

package/lib/exported.js

@@ -20,7 +20,7 @@ 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.StandardColors = exports.SfCommand = exports.SfHook = exports.generateTableChoices = exports.Prompter = exports.Progress = exports.Deauthorizer = exports.Deployer = exports.Deployable = exports.parseVarArgs = exports.toHelpSection = void 0;
+exports.Flags = exports.StandardColors = exports.SfCommand = exports.SfHook = exports.Ux = exports.generateTableChoices = exports.Prompter = exports.Progress = exports.Deauthorizer = exports.Deployer = exports.Deployable = exports.parseVarArgs = exports.toHelpSection = void 0;
 const core_1 = require("@oclif/core");
 var util_1 = require("./util");
 Object.defineProperty(exports, "toHelpSection", { enumerable: true, get: function () { return util_1.toHelpSection; } });
@@ -34,6 +34,7 @@ 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; } });
+Object.defineProperty(exports, "Ux", { enumerable: true, get: function () { return ux_1.Ux; } });
 var hooks_1 = require("./hooks");
 Object.defineProperty(exports, "SfHook", { enumerable: true, get: function () { return hooks_1.SfHook; } });
 __exportStar(require("./types"), exports);

package/lib/sfCommand.d.ts

@@ -1,5 +1,5 @@
 import { CliUx, Command, Config, HelpSection, Interfaces } from '@oclif/core';
-import { SfProject, StructuredMessage, SfError } from '@salesforce/core';
+import { SfProject, StructuredMessage, SfError, ConfigAggregator } from '@salesforce/core';
 import { AnyJson } from '@salesforce/ts-types';
 import * as chalk from 'chalk';
 import { Progress, Prompter, Spinner, Ux } from './ux';
@@ -129,6 +129,33 @@ export declare abstract class SfCommand<T> extends Command {
      */
     progress: Progress;
     project: SfProject;
+    /**
+     * ConfigAggregator instance for accessing global and local configuration.
+     *
+     * NOTE: If the active executable is sfdx, this will be an instance of SfdxConfigAggregator, which supports
+     * the deprecated sfdx config vars like defaultusername, defaultdevhubusername, apiversion, etc. Otherwise,
+     * it will be an instance of ConfigAggregator will only supports the config vars introduce by @salesforce/core@v3.
+     *
+     * The executable is determined by `this.config.bin` which is supplied by the base oclif/core Command class. The value
+     * of `this.config.bin` will be the executable running (e.g. sfdx or sf) or, for local development (e.g. using bin/dev),
+     * it will be the value of oclif.bin in the plugin's package.json.
+     *
+     * If you need to write NUTS for a plugin that needs to work with both sets of config vars you can
+     * use set the `SF_USE_DEPRECATED_CONFIG_VARS` to `true` to force configAggregator to be an instance of SfdxConfigAggregator or
+     * `false` to force configAggregator to be an instance of ConfigAggregator.
+     *
+     * @example
+     * ```
+     * import { execCmd } from '@salesforce/cli-plugins-testkit';
+     * execCmd('config:set defaultusername=test@example.com', {
+     *   env: {
+     *     ...process.env,
+     *     SF_USE_DEPRECATED_CONFIG_VARS: true,
+     *   }
+     * })
+     * ```
+     */
+    configAggregator: ConfigAggregator;
     private warnings;
     private ux;
     private prompter;

package/lib/sfCommand.js

@@ -10,6 +10,7 @@ exports.SfCommand = exports.StandardColors = void 0;
 const os = require("os");
 const core_1 = require("@oclif/core");
 const core_2 = require("@salesforce/core");
+const kit_1 = require("@salesforce/kit");
 const chalk = require("chalk");
 const ux_1 = require("./ux");
 core_2.Messages.importMessagesDirectory(__dirname);
@@ -56,10 +57,10 @@ class SfCommand extends core_1.Command {
         super(argv, config);
         this.warnings = [];
         const outputEnabled = !this.jsonEnabled();
-        this.spinner = new ux_1.Spinner(outputEnabled);
         this.progress = new ux_1.Progress(outputEnabled && core_2.envVars.getBoolean(core_2.EnvironmentVariable.SF_USE_PROGRESS_BAR, true));
         this.ux = new ux_1.Ux(outputEnabled);
-        this.prompter = new ux_1.Prompter();
+        this.spinner = this.ux.spinner;
+        this.prompter = this.ux.prompter;
         this.lifecycle = core_2.Lifecycle.getInstance();
     }
     get statics() {
@@ -187,6 +188,12 @@ class SfCommand extends core_1.Command {
         return this.prompter.timedPrompt(questions, ms, initialAnswers);
     }
     async _run() {
+        this.configAggregator =
+            this.config.bin === 'sfdx' ??
+                kit_1.env.getBoolean('SF_USE_DEPRECATED_CONFIG_VARS') ??
+                kit_1.env.getBoolean('SFDX_USE_DEPRECATED_CONFIG_VARS')
+                ? await core_2.SfdxConfigAggregator.create()
+                : await core_2.ConfigAggregator.create();
         if (this.statics.requiresProject) {
             this.project = await this.assignProject();
         }

package/lib/ux/base.d.ts

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

package/lib/ux/ux.d.ts

@@ -1,12 +1,76 @@
 import { CliUx } from '@oclif/core';
 import { AnyJson } from '@salesforce/ts-types';
 import { UxBase } from './base';
+import { Prompter } from './prompter';
+import { Spinner } from './spinner';
+/**
+ * UX methods for plugins. Automatically suppress console output if outputEnabled is set to false.
+ *
+ * @example
+ * ```
+ * import { SfCommand, Ux } from '@salesforce/sf-plugins-core';
+ * import { AnyJson } from '@salesforce/ts-types';
+ *
+ * class MyCommand extends SfCommand<AnyJson> {
+ *   public async run(): Promise<AnyJson> {
+ *     const ux = new Ux(!this.jsonEnabled());
+ *   }
+ * }
+ *
+ * ```
+ */
 export declare class Ux extends UxBase {
+    readonly outputEnabled: boolean;
+    spinner: Spinner;
+    prompter: Prompter;
     constructor(outputEnabled: boolean);
+    /**
+     * Log a message to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param message Message to log. Formatting is supported.
+     * @param args Args to be used for formatting.
+     */
+    log(message?: string, ...args: string[]): void;
+    /**
+     * Log a warning message to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param message Warning message to log.
+     */
+    warn(message: string | Error): void;
+    /**
+     * Display a table to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param data Data to be displayed
+     * @param columns Columns to display the data in
+     * @param options Options for how the table should be displayed
+     */
     table<T extends Ux.Table.Data>(data: T[], columns: Ux.Table.Columns<T>, options?: Ux.Table.Options): void;
+    /**
+     * Display a url to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param text text to display
+     * @param uri URL link
+     * @param params
+     */
     url(text: string, uri: string, params?: {}): void;
+    /**
+     * Display stylized JSON to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param obj JSON to display
+     */
     styledJSON(obj: AnyJson): void;
-    styledObject(obj: AnyJson): void;
+    /**
+     * Display stylized object to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param obj Object to display
+     * @param keys Keys of object to display
+     */
+    styledObject(obj: AnyJson, keys?: string[]): void;
+    /**
+     * Display stylized header to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param text header to display
+     */
     styledHeader(text: string): void;
 }
 export declare namespace Ux {

package/lib/ux/ux.js

@@ -9,22 +9,90 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Ux = void 0;
 const core_1 = require("@oclif/core");
 const base_1 = require("./base");
+const prompter_1 = require("./prompter");
+const spinner_1 = require("./spinner");
+/**
+ * UX methods for plugins. Automatically suppress console output if outputEnabled is set to false.
+ *
+ * @example
+ * ```
+ * import { SfCommand, Ux } from '@salesforce/sf-plugins-core';
+ * import { AnyJson } from '@salesforce/ts-types';
+ *
+ * class MyCommand extends SfCommand<AnyJson> {
+ *   public async run(): Promise<AnyJson> {
+ *     const ux = new Ux(!this.jsonEnabled());
+ *   }
+ * }
+ *
+ * ```
+ */
 class Ux extends base_1.UxBase {
     constructor(outputEnabled) {
         super(outputEnabled);
+        this.outputEnabled = outputEnabled;
+        this.spinner = new spinner_1.Spinner(outputEnabled);
+        this.prompter = new prompter_1.Prompter();
+    }
+    /**
+     * Log a message to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param message Message to log. Formatting is supported.
+     * @param args Args to be used for formatting.
+     */
+    log(message, ...args) {
+        this.maybeNoop(() => core_1.CliUx.ux.log(message, ...args));
+    }
+    /**
+     * Log a warning message to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param message Warning message to log.
+     */
+    warn(message) {
+        this.maybeNoop(() => core_1.CliUx.ux.warn(message));
     }
+    /**
+     * Display a table to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param data Data to be displayed
+     * @param columns Columns to display the data in
+     * @param options Options for how the table should be displayed
+     */
     table(data, columns, options) {
         this.maybeNoop(() => core_1.CliUx.ux.table(data, columns, options));
     }
+    /**
+     * Display a url to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param text text to display
+     * @param uri URL link
+     * @param params
+     */
     url(text, uri, params = {}) {
         this.maybeNoop(() => core_1.CliUx.ux.url(text, uri, params));
     }
+    /**
+     * Display stylized JSON to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param obj JSON to display
+     */
     styledJSON(obj) {
         this.maybeNoop(() => core_1.CliUx.ux.styledJSON(obj));
     }
-    styledObject(obj) {
-        this.maybeNoop(() => core_1.CliUx.ux.styledObject(obj));
+    /**
+     * Display stylized object to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param obj Object to display
+     * @param keys Keys of object to display
+     */
+    styledObject(obj, keys) {
+        this.maybeNoop(() => core_1.CliUx.ux.styledObject(obj, keys));
     }
+    /**
+     * Display stylized header to the console. This will be automatically suppressed if output is disabled.
+     *
+     * @param text header to display
+     */
     styledHeader(text) {
         this.maybeNoop(() => core_1.CliUx.ux.styledHeader(text));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sf-plugins-core",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Utils for writing deploy and retrieve plugins",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -32,24 +32,24 @@
     "/messages"
   ],
   "dependencies": {
-    "@oclif/core": "^1.16.4",
+    "@oclif/core": "^1.19.0",
     "@salesforce/core": "^3.30.9",
-    "@salesforce/kit": "^1.5.44",
+    "@salesforce/kit": "^1.7.0",
     "@salesforce/ts-types": "^1.5.20",
     "chalk": "^4",
     "inquirer": "^8.2.3"
   },
   "devDependencies": {
-    "@oclif/test": "^2.1.0",
+    "@oclif/test": "^2.2.4",
     "@salesforce/dev-config": "^3.0.0",
     "@salesforce/dev-scripts": "^3.1.0",
     "@salesforce/prettier-config": "^0.0.2",
     "@salesforce/ts-sinon": "^1.3.21",
     "@types/inquirer": "^8.2.3",
-    "@typescript-eslint/eslint-plugin": "^5.33.0",
-    "@typescript-eslint/parser": "^5.33.0",
+    "@typescript-eslint/eslint-plugin": "^5.40.0",
+    "@typescript-eslint/parser": "^5.40.0",
     "chai": "^4.3.6",
-    "eslint": "^8.21.0",
+    "eslint": "^8.25.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-config-salesforce": "^1.1.0",
     "eslint-config-salesforce-license": "^0.1.6",