@salesforce/core 4.0.0 → 4.1.0

package/lib/config/config.js

@@ -6,90 +6,106 @@
  * 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.Config = exports.SfProperty = exports.SFDX_ALLOWED_PROPERTIES = exports.SfdxPropertyKeys = void 0;
+exports.SfdxConfig = exports.Config = exports.SfProperty = exports.SFDX_ALLOWED_PROPERTIES = exports.SfdxPropertyKeys = exports.SF_ALLOWED_PROPERTIES = exports.SfConfigProperties = void 0;
 const path_1 = require("path");
+const fs = require("fs");
 const kit_1 = require("@salesforce/kit");
 const ts_types_1 = require("@salesforce/ts-types");
 const global_1 = require("../global");
 const logger_1 = require("../logger");
 const messages_1 = require("../messages");
 const sfdc_1 = require("../util/sfdc");
-const fs_1 = require("../util/fs");
 const sfdcUrl_1 = require("../util/sfdcUrl");
 const orgConfigProperties_1 = require("../org/orgConfigProperties");
+const lifecycleEvents_1 = require("../lifecycleEvents");
 const configFile_1 = require("./configFile");
-messages_1.Messages.importMessagesDirectory(__dirname);
-const messages = messages_1.Messages.load('@salesforce/core', 'config', [
-    'deprecatedConfigKey',
-    'invalidApiVersion',
-    'invalidBooleanConfigValue',
-    'invalidConfigValue',
-    'invalidInstanceUrl',
-    'invalidIsvDebuggerSid',
-    'invalidIsvDebuggerUrl',
-    'invalidNumberConfigValue',
-    'invalidWrite',
-    'unknownConfigKey',
-    'defaultUsername',
-    'defaultDevHubUsername',
-    'isvDebuggerSid',
-    'isvDebuggerUrl',
-    'apiVersion',
-    'disableTelemetry',
-    'maxQueryLimit',
-    'restDeploy',
-    'instanceUrl',
-]);
-const log = logger_1.Logger.childFromRoot('core:config');
+const messages = new messages_1.Messages('@salesforce/core', 'config', new Map([["unknownConfigKey", "Unknown config name: %s."], ["deprecatedConfigKey", "Deprecated config name: %s. Please use %s instead."], ["invalidWrite", "The writeSync method is not allowed on SfdxConfig. Use the async write method instead."], ["invalidConfigValue", "Invalid config value: %s."], ["invalidInstanceUrl", "Specify a valid Salesforce instance URL."], ["invalidApiVersion", "Specify a valid Salesforce API version, for example, 42.0."], ["invalidCustomOrgMetadataTemplates", "Specify a valid repository URL or directory for the custom org metadata templates."], ["invalidIsvDebuggerSid", "Specify a valid Debugger SID."], ["invalidIsvDebuggerUrl", "Specify a valid Debugger URL."], ["invalidNumberConfigValue", "Specify a valid positive integer, for example, 150000."], ["invalidBooleanConfigValue", "The config value can only be set to true or false."], ["invalidProjectWorkspace", "This directory does not contain a valid Salesforce DX project."], ["schemaValidationError", "The config file \"%s\" is not schema valid.\nDue to: %s"], ["schemaValidationError.actions", ["Fix the invalid entries at %s."]], ["missingDefaultPath", "In sfdx-project.json, be sure to specify which package directory (path) is the default. Example: `[{ \"path\": \"packageDirectory1\", \"default\": true }, { \"path\": \"packageDirectory2\" }]`"], ["missingPackageDirectory", "The path \"%s\", specified in sfdx-project.json, does not exist. Be sure this directory is included in your project root."], ["invalidPackageDirectory", "The path \"%s\", specified in sfdx-project.json, must be indicated as a relative path to the project root."], ["multipleDefaultPaths", "In sfdx-project.json, indicate only one package directory (path) as the default."], ["singleNonDefaultPackage", "The sfdx-project.json file must include one, and only one, default package directory (path). Because your sfdx-project.json file contains only one package directory, it must be the default. Remove the `\"default\": false` key and try again."], ["target-org", "Username or alias of the org that all commands run against by default. (sf only)"], ["target-dev-hub", "Username or alias of your default Dev Hub org. (sf only)"], ["defaultUsername", "Username or alias of the org that all commands run against by default. (sfdx only)"], ["defaultDevHubUsername", "Username or alias of your default Dev Hub org. (sfdx only)"], ["isvDebuggerSid", "ISV debugger SID (sfdx only)"], ["isvDebuggerUrl", "ISV debugger URL (sfdx only)"], ["org-isv-debugger-sid", "ISV debugger SID."], ["org-isv-debugger-url", "ISV debugger URL."], ["apiVersion", "API version of your project. Default: API version of your Dev Hub org. (sfdx only)"], ["org-api-version", "API version of your project. Default: API version of your Dev Hub org."], ["disableTelemetry", "Disables the collection of usage and user environment information, etc. Default: false. (sfdx only)"], ["disable-telemetry", "Disables the collection of usage and user environment information, etc. Default: false."], ["maxQueryLimit", "Maximum number of Salesforce records returned by a CLI command. Default: 10,000. (sfdx only)"], ["org-max-query-limit", "Maximum number of Salesforce records returned by a CLI command. Default: 10,000."], ["restDeploy", "Whether deployments use the Metadata REST API (true) or SOAP API (false, default value). (sfdx only)"], ["instanceUrl", "URL of the Salesforce instance hosting your org. Default: https://login.salesforce.com. (sfdx only)"], ["org-instance-url", "URL of the Salesforce instance hosting your org. Default: https://login.salesforce.com."], ["customOrgMetadataTemplates", "A valid repository URL or directory for the custom org metadata templates."], ["org-custom-metadata-templates", "A valid repository URL or directory for the custom org metadata templates."], ["invalidId", "The given id %s is not a valid 15 or 18 character Salesforce ID."]]));
 const SFDX_CONFIG_FILE_NAME = 'sfdx-config.json';
 const CONFIG_FILE_NAME = 'config.json';
+var SfConfigProperties;
+(function (SfConfigProperties) {
+    /**
+     * Disables telemetry reporting
+     */
+    SfConfigProperties["DISABLE_TELEMETRY"] = "disable-telemetry";
+})(SfConfigProperties = exports.SfConfigProperties || (exports.SfConfigProperties = {}));
+exports.SF_ALLOWED_PROPERTIES = [
+    {
+        key: SfConfigProperties.DISABLE_TELEMETRY,
+        description: messages.getMessage(SfConfigProperties.DISABLE_TELEMETRY),
+        input: {
+            validator: (value) => value == null || ['true', 'false'].includes(value.toString()),
+            failedMessage: messages.getMessage('invalidBooleanConfigValue'),
+        },
+    },
+];
 var SfdxPropertyKeys;
 (function (SfdxPropertyKeys) {
     /**
      * Username associated with the default dev hub org.
      *
      * @deprecated Replaced by OrgConfigProperties.TARGET_DEV_HUB in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
+     * will remain in v3 for the foreseeable future so that `sfdx-core` can map between `sf` and `sfdx` config values
      */
     SfdxPropertyKeys["DEFAULT_DEV_HUB_USERNAME"] = "defaultdevhubusername";
     /**
      * Username associate with the default org.
      *
      * @deprecated Replaced by OrgConfigProperties.TARGET_ORG in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
+     * will remain in v3 for the foreseeable future so that `sfdx-core` can map between `sf` and `sfdx` config values
      */
     SfdxPropertyKeys["DEFAULT_USERNAME"] = "defaultusername";
     /**
      * The sid for the debugger configuration.
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_ISV_DEBUGGER_SID in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     SfdxPropertyKeys["ISV_DEBUGGER_SID"] = "isvDebuggerSid";
     /**
      * The url for the debugger configuration.
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_ISV_DEBUGGER_URL in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     SfdxPropertyKeys["ISV_DEBUGGER_URL"] = "isvDebuggerUrl";
     /**
      * The api version
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_API_VERSION in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     SfdxPropertyKeys["API_VERSION"] = "apiVersion";
     /**
      * Disables telemetry reporting
+     *
+     * @deprecated Replaced by SfPropertyKeys.DISABLE_TELEMETRY in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     SfdxPropertyKeys["DISABLE_TELEMETRY"] = "disableTelemetry";
     /**
      * Custom templates repo or local location.
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_CUSTOM_METADATA_TEMPLATES in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     SfdxPropertyKeys["CUSTOM_ORG_METADATA_TEMPLATES"] = "customOrgMetadataTemplates";
     /**
      * allows users to override the 10,000 result query limit
+     *
+     * @deprecated Replaced by OrgConfigProperties.ORG_MAX_QUERY_LIMIT in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
      */
     SfdxPropertyKeys["MAX_QUERY_LIMIT"] = "maxQueryLimit";
-    /** */
+    /**
+     * @deprecated
+     */
     SfdxPropertyKeys["REST_DEPLOY"] = "restDeploy";
-    /** */
+    /**
+     * @deprecated Replaced by OrgConfigProperties.ORG_INSTANCE_URL in v3 {@link https://github.com/forcedotcom/sfdx-core/blob/v3/MIGRATING_V2-V3.md#config}
+     */
     SfdxPropertyKeys["INSTANCE_URL"] = "instanceUrl";
 })(SfdxPropertyKeys = exports.SfdxPropertyKeys || (exports.SfdxPropertyKeys = {}));
 exports.SFDX_ALLOWED_PROPERTIES = [
     {
         key: SfdxPropertyKeys.INSTANCE_URL,
         description: messages.getMessage(SfdxPropertyKeys.INSTANCE_URL),
+        newKey: orgConfigProperties_1.OrgConfigProperties.ORG_INSTANCE_URL,
+        deprecated: true,
         input: {
             // If a value is provided validate it otherwise no value is unset.
             validator: (value) => {
@@ -106,21 +122,25 @@ exports.SFDX_ALLOWED_PROPERTIES = [
     },
     {
         key: SfdxPropertyKeys.API_VERSION,
+        newKey: orgConfigProperties_1.OrgConfigProperties.ORG_API_VERSION,
+        deprecated: true,
         description: messages.getMessage(SfdxPropertyKeys.API_VERSION),
         hidden: true,
         input: {
             // If a value is provided validate it otherwise no value is unset.
-            validator: (value) => value == null || ((0, ts_types_1.isString)(value) && sfdc_1.sfdc.validateApiVersion(value)),
+            validator: (value) => value == null || ((0, ts_types_1.isString)(value) && (0, sfdc_1.validateApiVersion)(value)),
             failedMessage: messages.getMessage('invalidApiVersion'),
         },
     },
     {
+        // will remain in v3 for the foreseeable future so that `sfdx-core` can map between `sf` and `sfdx` config values
         key: SfdxPropertyKeys.DEFAULT_DEV_HUB_USERNAME,
         newKey: orgConfigProperties_1.OrgConfigProperties.TARGET_DEV_HUB,
         deprecated: true,
         description: messages.getMessage('defaultDevHubUsername'),
     },
     {
+        // will remain in v3 for the foreseeable future so that `sfdx-core` can map between `sf` and `sfdx` config values
         key: SfdxPropertyKeys.DEFAULT_USERNAME,
         newKey: orgConfigProperties_1.OrgConfigProperties.TARGET_ORG,
         deprecated: true,
@@ -128,6 +148,8 @@ exports.SFDX_ALLOWED_PROPERTIES = [
     },
     {
         key: SfdxPropertyKeys.ISV_DEBUGGER_SID,
+        newKey: orgConfigProperties_1.OrgConfigProperties.ORG_ISV_DEBUGGER_SID,
+        deprecated: true,
         description: messages.getMessage(SfdxPropertyKeys.ISV_DEBUGGER_SID),
         encrypted: true,
         input: {
@@ -138,6 +160,8 @@ exports.SFDX_ALLOWED_PROPERTIES = [
     },
     {
         key: SfdxPropertyKeys.ISV_DEBUGGER_URL,
+        newKey: orgConfigProperties_1.OrgConfigProperties.ORG_ISV_DEBUGGER_URL,
+        deprecated: true,
         description: messages.getMessage(SfdxPropertyKeys.ISV_DEBUGGER_URL),
         input: {
             // If a value is provided validate it otherwise no value is unset.
@@ -147,17 +171,26 @@ exports.SFDX_ALLOWED_PROPERTIES = [
     },
     {
         key: SfdxPropertyKeys.DISABLE_TELEMETRY,
+        newKey: SfConfigProperties.DISABLE_TELEMETRY,
+        deprecated: true,
         description: messages.getMessage(SfdxPropertyKeys.DISABLE_TELEMETRY),
         input: {
             validator: (value) => value == null || ['true', 'false'].includes(value.toString()),
             failedMessage: messages.getMessage('invalidBooleanConfigValue'),
         },
     },
-    // This should be brought in by a plugin, but there isn't a way to do that right now.
+    {
+        key: SfdxPropertyKeys.CUSTOM_ORG_METADATA_TEMPLATES,
+        newKey: orgConfigProperties_1.OrgConfigProperties.ORG_CUSTOM_METADATA_TEMPLATES,
+        deprecated: true,
+        description: messages.getMessage(SfdxPropertyKeys.CUSTOM_ORG_METADATA_TEMPLATES),
+    },
     {
         key: SfdxPropertyKeys.REST_DEPLOY,
         description: messages.getMessage(SfdxPropertyKeys.REST_DEPLOY),
         hidden: true,
+        newKey: 'org-metadata-rest-deploy',
+        deprecated: true,
         input: {
             validator: (value) => value != null && ['true', 'false'].includes(value.toString()),
             failedMessage: messages.getMessage('invalidBooleanConfigValue'),
@@ -166,6 +199,9 @@ exports.SFDX_ALLOWED_PROPERTIES = [
     {
         key: SfdxPropertyKeys.MAX_QUERY_LIMIT,
         description: messages.getMessage(SfdxPropertyKeys.MAX_QUERY_LIMIT),
+        hidden: true,
+        newKey: orgConfigProperties_1.OrgConfigProperties.ORG_MAX_QUERY_LIMIT,
+        deprecated: true,
         input: {
             // the bit shift will remove the negative bit, and any decimal numbers
             // then the parseFloat will handle converting it to a number from a string
@@ -193,7 +229,7 @@ class Config extends configFile_1.ConfigFile {
     constructor(options) {
         super(Object.assign({
             isGlobal: false,
-        }, options !== null && options !== void 0 ? options : {}, {
+        }, options ?? {}, {
             // Don't let consumers of config override this. If they really really want to,
             // they can extend this class.
             isState: true,
@@ -225,9 +261,12 @@ class Config extends configFile_1.ConfigFile {
      */
     static addAllowedProperties(metas) {
         const currentMetaKeys = Object.keys(Config.propertyConfigMap());
+        // If logger is needed elsewhere in this file, do not move this outside of the Config class.
+        // It was causing issues with Bunyan log rotation. See https://github.com/forcedotcom/sfdx-core/pull/562
+        const logger = logger_1.Logger.childFromRoot('core:config');
         metas.forEach((meta) => {
             if (currentMetaKeys.includes(meta.key)) {
-                log.info(`Key ${meta.key} already exists in allowedProperties, skipping.`);
+                logger.info(`Key ${meta.key} already exists in allowedProperties, skipping.`);
                 return;
             }
             Config.allowedProperties.push(meta);
@@ -262,6 +301,13 @@ class Config extends configFile_1.ConfigFile {
         localConfig.clear();
         await localConfig.write();
     }
+    static getPropertyConfigMeta(propertyName) {
+        const prop = Config.propertyConfigMap()[propertyName];
+        if (prop?.deprecated && prop?.newKey) {
+            return Config.propertyConfigMap()[prop.newKey];
+        }
+        return prop;
+    }
     static propertyConfigMap() {
         return (0, kit_1.keyBy)(Config.allowedProperties, 'key');
     }
@@ -300,7 +346,7 @@ class Config extends configFile_1.ConfigFile {
         await this.cryptProperties(true);
         await super.write();
         if (global_1.Global.SFDX_INTEROPERABILITY)
-            await this.sfdxConfig.writeSync();
+            await this.sfdxConfig.write();
         await this.cryptProperties(false);
         return this.getContents();
     }
@@ -308,19 +354,19 @@ class Config extends configFile_1.ConfigFile {
      * DO NOT CALL - The config file needs to encrypt values which can only be done asynchronously.
      * Call {@link SfdxConfig.write} instead.
      *
-     * **Throws** *{@link SfdxError}{ name: 'InvalidWriteError' }* Always.
+     * **Throws** *{@link SfError}{ name: 'InvalidWriteError' }* Always.
      *
      * @param newContents Contents to write
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars, class-methods-use-this
     writeSync(newContents) {
         throw messages.createError('invalidWrite');
     }
     /**
      * Sets a value for a property.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
-     * **Throws** *{@link SfdxError}{ name: 'InvalidConfigValueError' }* If the input validator fails.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
+     * **Throws** *{@link SfError}{ name: 'InvalidConfigValueError' }* If the input validator fails.
      *
      * @param key The property to set.
      * @param value The value of the property.
@@ -331,14 +377,16 @@ class Config extends configFile_1.ConfigFile {
             throw messages.createError('unknownConfigKey', [key]);
         }
         if (property.deprecated && property.newKey) {
-            throw messages.createError('deprecatedConfigKey', [key, property.newKey]);
+            // you're trying to set a deprecated key, but we'll set the new key instead
+            void lifecycleEvents_1.Lifecycle.getInstance().emitWarning(messages.getMessage('deprecatedConfigKey', [key, property.newKey]));
+            return this.set(property.newKey, value);
         }
         if (property.input) {
-            if (property.input && property.input.validator(value)) {
+            if (property.input?.validator(value)) {
                 super.set(property.key, value);
             }
             else {
-                let valueError = (value === null || value === void 0 ? void 0 : value.toString()) || '';
+                let valueError = value?.toString() ?? '';
                 if (property.input.failedMessage) {
                     valueError = (0, ts_types_1.isString)(property.input.failedMessage)
                         ? property.input.failedMessage
@@ -355,7 +403,7 @@ class Config extends configFile_1.ConfigFile {
     /**
      * Unsets a value for a property.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* If the input validator fails.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* If the input validator fails.
      *
      * @param key The property to unset.
      */
@@ -365,20 +413,28 @@ class Config extends configFile_1.ConfigFile {
             throw messages.createError('unknownConfigKey', [key]);
         }
         if (property.deprecated && property.newKey) {
-            throw messages.createError('deprecatedConfigKey', [key, property.newKey]);
+            // you're trying to set a deprecated key, so we'll ALSO unset the new key
+            void lifecycleEvents_1.Lifecycle.getInstance().emitWarning(messages.getMessage('deprecatedConfigKey', [key, property.newKey]));
+            super.unset(property.key);
+            return this.unset(property.newKey);
         }
         return super.unset(property.key);
     }
     /**
      * Get an individual property config.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
      *
      * @param propertyName The name of the property.
      */
+    // eslint-disable-next-line class-methods-use-this
     getPropertyConfig(propertyName) {
         const prop = Config.propertyConfigMap()[propertyName];
         if (!prop) {
+            const newEquivalent = Config.allowedProperties.find((p) => p.newKey);
+            if (newEquivalent) {
+                return this.getPropertyConfig(newEquivalent.key);
+            }
             throw messages.createError('unknownConfigKey', [propertyName]);
         }
         return prop;
@@ -397,10 +453,7 @@ class Config extends configFile_1.ConfigFile {
      * @param encrypt `true` to encrypt.
      */
     async cryptProperties(encrypt) {
-        const hasEncryptedProperties = this.entries().some(([key]) => {
-            var _a;
-            return !!((_a = Config.propertyConfigMap()[key]) === null || _a === void 0 ? void 0 : _a.encrypted);
-        });
+        const hasEncryptedProperties = this.entries().some(([key]) => !!Config.propertyConfigMap()[key]?.encrypted);
         if (hasEncryptedProperties) {
             await this.initCrypto();
             const crypto = (0, ts_types_1.ensure)(this.crypto);
@@ -415,6 +468,7 @@ class Config extends configFile_1.ConfigFile {
 exports.Config = Config;
 Config.allowedProperties = [
     ...exports.SFDX_ALLOWED_PROPERTIES,
+    ...exports.SF_ALLOWED_PROPERTIES,
     ...orgConfigProperties_1.ORG_CONFIG_ALLOWED_PROPERTIES,
 ];
 class SfdxConfig {
@@ -444,38 +498,36 @@ class SfdxConfig {
         }
         return Object.assign(config, sfdxConfig);
     }
-    readSync() {
+    async write(config = this.config.toObject()) {
         try {
-            const contents = fs_1.fs.readJsonMapSync(this.getSfdxPath());
-            return this.normalize(contents, 'toNew');
+            const translated = this.translate(config, 'toOld');
+            const sfdxPath = this.getSfdxPath();
+            await fs.promises.mkdir((0, path_1.dirname)(sfdxPath), { recursive: true });
+            await fs.promises.writeFile(sfdxPath, JSON.stringify(translated, null, 2));
         }
         catch (error) {
             /* Do nothing */
-            return {};
         }
     }
-    async writeSync(config = this.config.toObject()) {
+    readSync() {
         try {
-            const sfdxPath = this.getSfdxPath();
-            await fs_1.fs.mkdirp((0, path_1.dirname)(sfdxPath));
-            const mapped = this.normalize(config, 'toOld');
-            await fs_1.fs.writeJson(sfdxPath, mapped);
+            const contents = (0, kit_1.parseJsonMap)(fs.readFileSync(this.getSfdxPath(), 'utf8'));
+            return this.translate(contents, 'toNew');
         }
         catch (error) {
             /* Do nothing */
+            return {};
         }
     }
     getSfdxPath() {
         if (!this.sfdxPath) {
             const stateFolder = global_1.Global.SFDX_STATE_FOLDER;
             const fileName = SFDX_CONFIG_FILE_NAME;
-            const _isGlobal = (0, ts_types_1.isBoolean)(this.options.isGlobal) && this.options.isGlobal;
-            const _isState = (0, ts_types_1.isBoolean)(this.options.isState) && this.options.isState;
             // Don't let users store config files in homedir without being in the state folder.
             let configRootFolder = this.options.rootFolder
                 ? this.options.rootFolder
                 : configFile_1.ConfigFile.resolveRootFolderSync(!!this.options.isGlobal);
-            if (_isGlobal || _isState) {
+            if (this.options.isGlobal === true || this.options.isState === true) {
                 configRootFolder = (0, path_1.join)(configRootFolder, stateFolder);
             }
             this.sfdxPath = (0, path_1.join)(configRootFolder, fileName);
@@ -489,22 +541,22 @@ class SfdxConfig {
      * If toOld is specified: migrate all deprecated configs back to their original key.
      * - For example, target-org will be renamed to defaultusername.
      */
-    normalize(contents, direction) {
-        var _a;
-        const mapped = {};
+    translate(contents, direction) {
+        const translated = {};
         for (const [key, value] of Object.entries(contents)) {
             const propConfig = direction === 'toNew'
                 ? this.config.getPropertyConfig(key)
-                : (_a = Config.getAllowedProperties().find((c) => c.newKey === key)) !== null && _a !== void 0 ? _a : {};
+                : Config.getAllowedProperties().find((c) => c.newKey === key) ?? {};
             if (propConfig.deprecated && propConfig.newKey) {
                 const normalizedKey = direction === 'toNew' ? propConfig.newKey : propConfig.key;
-                mapped[normalizedKey] = value;
+                translated[normalizedKey] = value;
             }
             else {
-                mapped[key] = value;
+                translated[key] = value;
             }
         }
-        return mapped;
+        return translated;
     }
 }
+exports.SfdxConfig = SfdxConfig;
 //# sourceMappingURL=config.js.map

package/lib/config/configAggregator.d.ts

@@ -1,5 +1,5 @@
 import { AsyncOptionalCreatable } from '@salesforce/kit';
-import { AnyJson, JsonMap, Optional } from '@salesforce/ts-types';
+import { AnyJson, Dictionary, JsonMap, Optional } from '@salesforce/ts-types';
 import { Config, ConfigPropertyMeta } from './config';
 /**
  * Information about a config property.
@@ -40,11 +40,11 @@ export interface ConfigInfo {
 }
 /**
  * Aggregate global and local project config files, as well as environment variables for
- * `sfdx-config.json`. The resolution happens in the following bottom-up order:
+ * `config.json`. The resolution happens in the following bottom-up order:
  *
- * 1. Environment variables  (`SFDX_LOG_LEVEL`)
- * 1. Workspace settings  (`<workspace-root>/.sfdx/sfdx-config.json`)
- * 1. Global settings  (`$HOME/.sfdx/sfdx-config.json`)
+ * 1. Environment variables  (`SF_LOG_LEVEL`)
+ * 1. Workspace settings  (`<workspace-root>/.sf/config.json`)
+ * 1. Global settings  (`$HOME/.sf/config.json`)
  *
  * Use {@link ConfigAggregator.create} to instantiate the aggregator.
  *
@@ -53,27 +53,21 @@ export interface ConfigInfo {
  * console.log(aggregator.getPropertyValue('target-org'));
  * ```
  */
-export declare class ConfigAggregator extends AsyncOptionalCreatable<JsonMap> {
-    private static instance;
-    private static encrypted;
+export declare class ConfigAggregator extends AsyncOptionalCreatable<ConfigAggregator.Options> {
+    protected static instance: AsyncOptionalCreatable;
+    protected static encrypted: boolean;
     private allowedProperties;
     private localConfig?;
     private globalConfig;
     private envVars;
-    private get config();
     /**
      * **Do not directly construct instances of this class -- use {@link ConfigAggregator.create} instead.**
      *
      * @ignore
      */
-    constructor(options?: JsonMap);
-    /**
-     * Get the static ConfigAggregator instance. If one doesn't exist, one will be created with
-     * the **encrypted** config values. Encrypted config values need to be resolved
-     * asynchronously by calling {@link ConfigAggregator.reload}
-     */
-    static getInstance<P, T extends AsyncOptionalCreatable<P>>(this: new () => T): T;
-    static create<P, T extends AsyncOptionalCreatable<P>>(this: new (options?: P) => T, options?: P): Promise<T>;
+    constructor(options?: ConfigAggregator.Options);
+    private get config();
+    static create<P extends ConfigAggregator.Options, T extends AsyncOptionalCreatable<P>>(this: new (options?: P) => T, options?: P): Promise<T>;
     /**
      * Get the info for a given key. If the ConfigAggregator was not asynchronously created OR
      * the {@link ConfigAggregator.reload} was not called, the config value may be encrypted.
@@ -81,28 +75,37 @@ export declare class ConfigAggregator extends AsyncOptionalCreatable<JsonMap> {
      * @param key The config key.
      */
     static getValue(key: string): ConfigInfo;
+    /**
+     * Get the static ConfigAggregator instance. If one doesn't exist, one will be created with
+     * the **encrypted** config values. Encrypted config values need to be resolved
+     * asynchronously by calling {@link ConfigAggregator.reload}
+     */
+    private static getInstance;
     /**
      * Initialize this instances async dependencies.
      */
     init(): Promise<void>;
     /**
      * Get a resolved config property.
+     * If you use a deprecated property, a warning will be emitted and it will attempt to resolve the new property's value
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
      *
      * @param key The key of the property.
      */
     getPropertyValue<T extends AnyJson>(key: string): Optional<T>;
     /**
      * Get a resolved config property meta.
+     * If the property is deprecated, it will return the new key's meta, if it exists, with a deprecation warning
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
+     * **Throws** *{@link SfError}{ name: 'UnknownConfigKeyError' }* An attempt to get a property that's not supported.
      *
      * @param key The key of the property.
      */
     getPropertyMeta(key: string): ConfigPropertyMeta;
     /**
      * Get a resolved config property.
+     * If a property is deprecated, it will try to use the the new key, if there is a config there.
      *
      * @param key The key of the property.
      * @param throwOnDeprecation True, if you want an error throw when reading a deprecated config
@@ -123,9 +126,9 @@ export declare class ConfigAggregator extends AsyncOptionalCreatable<JsonMap> {
      * Get a resolved file path or environment variable name of the property.
      *
      * For example, `getPath('logLevel')` will return:
-     * 1. `$SFDX_LOG_LEVEL` if resolved to an environment variable.
-     * 1. `./.sfdx/sfdx-config.json` if resolved to the local config.
-     * 1. `~/.sfdx/sfdx-config.json` if resolved to the global config.
+     * 1. `$SF_LOG_LEVEL` if resolved to an environment variable.
+     * 1. `./.sf/config.json` if resolved to the local config.
+     * 1. `~/.sf/config.json` if resolved to the global config.
      * 1. `undefined`, if not resolved.
      *
      * **Note:** that the path returned may be the absolute path instead of
@@ -140,7 +143,7 @@ export declare class ConfigAggregator extends AsyncOptionalCreatable<JsonMap> {
      * ```
      * > console.log(aggregator.getConfigInfo());
      * [
-     *     { key: 'logLevel', val: 'INFO', location: 'Environment', path: '$SFDX_LOG_LEVEL'}
+     *     { key: 'logLevel', val: 'INFO', location: 'Environment', path: '$SF_LOG_LEVEL'}
      *     { key: 'target-org', val: '<username>', location: 'Local', path: './.sf/config.json'}
      * ]
      * ```
@@ -161,7 +164,7 @@ export declare class ConfigAggregator extends AsyncOptionalCreatable<JsonMap> {
     /**
      * Get the config properties that are environment variables.
      */
-    getEnvVars(): Map<string, string>;
+    getEnvVars(): Dictionary<string>;
     /**
      * Re-read all property configurations from disk.
      */
@@ -171,24 +174,24 @@ export declare class ConfigAggregator extends AsyncOptionalCreatable<JsonMap> {
      */
     addAllowedProperties(configMetas: ConfigPropertyMeta | ConfigPropertyMeta[]): void;
     /**
-     * Loads all the properties and aggregates them according to location.
+     * Set the allowed properties.
+     *
+     * @param properties The properties to set.
      */
-    private loadProperties;
+    protected setAllowedProperties(properties: ConfigPropertyMeta[]): void;
     /**
-     * Loads all the properties and aggregates them according to location.
+     * Get the allowed properties.
      */
-    private loadPropertiesSync;
-    private resolveProperties;
+    protected getAllowedProperties(): ConfigPropertyMeta[];
     /**
-     * Get the allowed properties.
+     * Loads all the properties and aggregates them according to location.
      */
-    private getAllowedProperties;
+    protected loadProperties(): Promise<void>;
     /**
-     * Set the allowed properties.
-     *
-     * @param properties The properties to set.
+     * Loads all the properties and aggregates them according to location.
      */
-    private setAllowedProperties;
+    private loadPropertiesSync;
+    private resolveProperties;
 }
 export declare namespace ConfigAggregator {
     /**
@@ -208,4 +211,7 @@ export declare namespace ConfigAggregator {
          */
         ENVIRONMENT = "Environment"
     }
+    type Options = {
+        customConfigMeta?: ConfigPropertyMeta[];
+    };
 }