@salesforce/core 4.0.0-v3.0 → 4.0.1

package/lib/exported.d.ts

@@ -1,31 +1,38 @@
-export { OAuth2Options } from 'jsforce';
-export { Aliases, AliasGroup } from './config/aliases';
+export { OAuth2Config } from 'jsforce';
 export { ConfigFile } from './config/configFile';
-export { ConfigGroup } from './config/configGroup';
-export { BaseConfigStore, ConfigContents, ConfigEntry, ConfigStore, ConfigValue } from './config/configStore';
-export { GlobalInfo, SfEntry, SfInfo, SfInfoKeys, SfOrg, SfOrgs, SfToken, SfTokens } from './config/globalInfoConfig';
+export { TTLConfig } from './config/ttlConfig';
+export { envVars, EnvironmentVariable, SUPPORTED_ENV_VARS, EnvVars } from './config/envVars';
+export { ConfigContents, ConfigEntry, ConfigStore, ConfigValue } from './config/configStore';
+export { SfTokens, StateAggregator } from './stateAggregator';
 export { DeviceOauthService, DeviceCodeResponse, DeviceCodePollingResponse } from './deviceOauthService';
 export { OrgUsersConfig } from './config/orgUsersConfig';
-export { ConfigPropertyMeta, ConfigPropertyMetaInput, Config } from './config/config';
+export { ConfigPropertyMeta, ConfigPropertyMetaInput, Config, SfdxPropertyKeys, SfConfigProperties, SFDX_ALLOWED_PROPERTIES, SF_ALLOWED_PROPERTIES, } from './config/config';
+export { SandboxRequestCacheEntry, SandboxRequestCache } from './config/sandboxProcessCache';
 export { ConfigInfo, ConfigAggregator } from './config/configAggregator';
-export { AuthFields, AuthInfo, OAuth2WithVerifier, SfdcUrl, getJwtAudienceUrl } from './org/authInfo';
+export { AuthFields, AuthInfo, AuthSideEffects, OrgAuthorization } from './org/authInfo';
 export { AuthRemover } from './org/authRemover';
 export { Connection, SFDX_HTTP_HEADERS } from './org/connection';
 export { Mode, Global } from './global';
 export { Lifecycle } from './lifecycleEvents';
 export { WebOAuthServer } from './webOAuthServer';
+export { SfdcUrl } from './util/sfdcUrl';
+export { getJwtAudienceUrl } from './util/getJwtAudienceUrl';
 export { Fields, FieldValue, LoggerLevel, LoggerLevelValue, LogLine, LoggerOptions, LoggerStream, Logger, } from './logger';
-export { Messages } from './messages';
-export { Org } from './org/org';
-export { PackageDir, NamedPackageDir, PackageDirDependency, SfdxProject, SfdxProjectJson } from './sfdxProject';
-export { SchemaPrinter } from './schema/printer';
+export { Messages, StructuredMessage } from './messages';
+export { Org, SandboxProcessObject, StatusEvent, SandboxEvents, SandboxUserAuthResponse, SandboxUserAuthRequest, SandboxRequest, ResumeSandboxRequest, OrgTypes, ResultEvent, ScratchOrgRequest, } from './org';
+export { OrgConfigProperties, ORG_CONFIG_ALLOWED_PROPERTIES } from './org/orgConfigProperties';
+export { PackageDir, NamedPackageDir, PackageDirDependency, SfProject, SfProjectJson } from './sfProject';
 export { SchemaValidator } from './schema/validator';
-export { SfdxError } from './sfdxError';
-export { StatusResult } from './status/client';
+export { SchemaPrinter } from './schema/printer';
+export { SfError } from './sfError';
 export { PollingClient } from './status/pollingClient';
-export { CometClient, CometSubscription, StreamingClient } from './status/streamingClient';
+export { CometClient, CometSubscription, StreamingClient, StatusResult } from './status/streamingClient';
 export { MyDomainResolver } from './status/myDomainResolver';
 export { DefaultUserFields, REQUIRED_FIELDS, User, UserFields } from './org/user';
 export { PermissionSetAssignment, PermissionSetAssignmentFields } from './org/permissionSetAssignment';
-export * from './util/fs';
+export { ScratchOrgCreateOptions, ScratchOrgCreateResult, scratchOrgCreate, scratchOrgResume, } from './org/scratchOrgCreate';
+export { ScratchOrgInfo } from './org/scratchOrgTypes';
+export { ScratchOrgLifecycleEvent, scratchOrgLifecycleEventName, scratchOrgLifecycleStages, } from './org/scratchOrgLifecycleEvents';
+export { ScratchOrgCache } from './org/scratchOrgCache';
 export * from './util/sfdc';
+export * from './util/sfdcUrl';

package/lib/exported.js

@@ -7,42 +7,49 @@
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !exports.hasOwnProperty(p)) __createBinding(exports, m, p);
+    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.scratchOrgLifecycleEventName = exports.scratchOrgResume = exports.scratchOrgCreate = exports.PermissionSetAssignment = exports.User = exports.REQUIRED_FIELDS = exports.DefaultUserFields = exports.MyDomainResolver = exports.StreamingClient = exports.CometClient = exports.PollingClient = exports.SfError = exports.SchemaPrinter = exports.SchemaValidator = exports.SfProjectJson = exports.SfProject = exports.ORG_CONFIG_ALLOWED_PROPERTIES = exports.OrgConfigProperties = exports.OrgTypes = exports.SandboxEvents = exports.Org = exports.Messages = exports.Logger = exports.LoggerLevel = exports.getJwtAudienceUrl = exports.SfdcUrl = exports.WebOAuthServer = exports.Lifecycle = exports.Global = exports.Mode = exports.SFDX_HTTP_HEADERS = exports.Connection = exports.AuthRemover = exports.AuthInfo = exports.ConfigAggregator = exports.SandboxRequestCache = exports.SF_ALLOWED_PROPERTIES = exports.SFDX_ALLOWED_PROPERTIES = exports.SfConfigProperties = exports.SfdxPropertyKeys = exports.Config = exports.OrgUsersConfig = exports.DeviceOauthService = exports.StateAggregator = exports.EnvVars = exports.SUPPORTED_ENV_VARS = exports.EnvironmentVariable = exports.envVars = exports.TTLConfig = exports.ConfigFile = void 0;
+exports.ScratchOrgCache = exports.scratchOrgLifecycleStages = void 0;
 const messages_1 = require("./messages");
-messages_1.Messages.importMessagesDirectory(__dirname);
-var aliases_1 = require("./config/aliases");
-Object.defineProperty(exports, "Aliases", { enumerable: true, get: function () { return aliases_1.Aliases; } });
-Object.defineProperty(exports, "AliasGroup", { enumerable: true, get: function () { return aliases_1.AliasGroup; } });
 var configFile_1 = require("./config/configFile");
 Object.defineProperty(exports, "ConfigFile", { enumerable: true, get: function () { return configFile_1.ConfigFile; } });
-var configGroup_1 = require("./config/configGroup");
-Object.defineProperty(exports, "ConfigGroup", { enumerable: true, get: function () { return configGroup_1.ConfigGroup; } });
-var configStore_1 = require("./config/configStore");
-Object.defineProperty(exports, "BaseConfigStore", { enumerable: true, get: function () { return configStore_1.BaseConfigStore; } });
-var globalInfoConfig_1 = require("./config/globalInfoConfig");
-Object.defineProperty(exports, "GlobalInfo", { enumerable: true, get: function () { return globalInfoConfig_1.GlobalInfo; } });
-Object.defineProperty(exports, "SfInfoKeys", { enumerable: true, get: function () { return globalInfoConfig_1.SfInfoKeys; } });
+var ttlConfig_1 = require("./config/ttlConfig");
+Object.defineProperty(exports, "TTLConfig", { enumerable: true, get: function () { return ttlConfig_1.TTLConfig; } });
+var envVars_1 = require("./config/envVars");
+Object.defineProperty(exports, "envVars", { enumerable: true, get: function () { return envVars_1.envVars; } });
+Object.defineProperty(exports, "EnvironmentVariable", { enumerable: true, get: function () { return envVars_1.EnvironmentVariable; } });
+Object.defineProperty(exports, "SUPPORTED_ENV_VARS", { enumerable: true, get: function () { return envVars_1.SUPPORTED_ENV_VARS; } });
+Object.defineProperty(exports, "EnvVars", { enumerable: true, get: function () { return envVars_1.EnvVars; } });
+var stateAggregator_1 = require("./stateAggregator");
+Object.defineProperty(exports, "StateAggregator", { enumerable: true, get: function () { return stateAggregator_1.StateAggregator; } });
 var deviceOauthService_1 = require("./deviceOauthService");
 Object.defineProperty(exports, "DeviceOauthService", { enumerable: true, get: function () { return deviceOauthService_1.DeviceOauthService; } });
 var orgUsersConfig_1 = require("./config/orgUsersConfig");
 Object.defineProperty(exports, "OrgUsersConfig", { enumerable: true, get: function () { return orgUsersConfig_1.OrgUsersConfig; } });
 var config_1 = require("./config/config");
 Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_1.Config; } });
+Object.defineProperty(exports, "SfdxPropertyKeys", { enumerable: true, get: function () { return config_1.SfdxPropertyKeys; } });
+Object.defineProperty(exports, "SfConfigProperties", { enumerable: true, get: function () { return config_1.SfConfigProperties; } });
+Object.defineProperty(exports, "SFDX_ALLOWED_PROPERTIES", { enumerable: true, get: function () { return config_1.SFDX_ALLOWED_PROPERTIES; } });
+Object.defineProperty(exports, "SF_ALLOWED_PROPERTIES", { enumerable: true, get: function () { return config_1.SF_ALLOWED_PROPERTIES; } });
+var sandboxProcessCache_1 = require("./config/sandboxProcessCache");
+Object.defineProperty(exports, "SandboxRequestCache", { enumerable: true, get: function () { return sandboxProcessCache_1.SandboxRequestCache; } });
 var configAggregator_1 = require("./config/configAggregator");
 Object.defineProperty(exports, "ConfigAggregator", { enumerable: true, get: function () { return configAggregator_1.ConfigAggregator; } });
 var authInfo_1 = require("./org/authInfo");
 Object.defineProperty(exports, "AuthInfo", { enumerable: true, get: function () { return authInfo_1.AuthInfo; } });
-Object.defineProperty(exports, "OAuth2WithVerifier", { enumerable: true, get: function () { return authInfo_1.OAuth2WithVerifier; } });
-Object.defineProperty(exports, "SfdcUrl", { enumerable: true, get: function () { return authInfo_1.SfdcUrl; } });
-Object.defineProperty(exports, "getJwtAudienceUrl", { enumerable: true, get: function () { return authInfo_1.getJwtAudienceUrl; } });
 var authRemover_1 = require("./org/authRemover");
 Object.defineProperty(exports, "AuthRemover", { enumerable: true, get: function () { return authRemover_1.AuthRemover; } });
 var connection_1 = require("./org/connection");
@@ -55,22 +62,31 @@ var lifecycleEvents_1 = require("./lifecycleEvents");
 Object.defineProperty(exports, "Lifecycle", { enumerable: true, get: function () { return lifecycleEvents_1.Lifecycle; } });
 var webOAuthServer_1 = require("./webOAuthServer");
 Object.defineProperty(exports, "WebOAuthServer", { enumerable: true, get: function () { return webOAuthServer_1.WebOAuthServer; } });
+var sfdcUrl_1 = require("./util/sfdcUrl");
+Object.defineProperty(exports, "SfdcUrl", { enumerable: true, get: function () { return sfdcUrl_1.SfdcUrl; } });
+var getJwtAudienceUrl_1 = require("./util/getJwtAudienceUrl");
+Object.defineProperty(exports, "getJwtAudienceUrl", { enumerable: true, get: function () { return getJwtAudienceUrl_1.getJwtAudienceUrl; } });
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "LoggerLevel", { enumerable: true, get: function () { return logger_1.LoggerLevel; } });
 Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
 var messages_2 = require("./messages");
 Object.defineProperty(exports, "Messages", { enumerable: true, get: function () { return messages_2.Messages; } });
-var org_1 = require("./org/org");
+var org_1 = require("./org");
 Object.defineProperty(exports, "Org", { enumerable: true, get: function () { return org_1.Org; } });
-var sfdxProject_1 = require("./sfdxProject");
-Object.defineProperty(exports, "SfdxProject", { enumerable: true, get: function () { return sfdxProject_1.SfdxProject; } });
-Object.defineProperty(exports, "SfdxProjectJson", { enumerable: true, get: function () { return sfdxProject_1.SfdxProjectJson; } });
-var printer_1 = require("./schema/printer");
-Object.defineProperty(exports, "SchemaPrinter", { enumerable: true, get: function () { return printer_1.SchemaPrinter; } });
+Object.defineProperty(exports, "SandboxEvents", { enumerable: true, get: function () { return org_1.SandboxEvents; } });
+Object.defineProperty(exports, "OrgTypes", { enumerable: true, get: function () { return org_1.OrgTypes; } });
+var orgConfigProperties_1 = require("./org/orgConfigProperties");
+Object.defineProperty(exports, "OrgConfigProperties", { enumerable: true, get: function () { return orgConfigProperties_1.OrgConfigProperties; } });
+Object.defineProperty(exports, "ORG_CONFIG_ALLOWED_PROPERTIES", { enumerable: true, get: function () { return orgConfigProperties_1.ORG_CONFIG_ALLOWED_PROPERTIES; } });
+var sfProject_1 = require("./sfProject");
+Object.defineProperty(exports, "SfProject", { enumerable: true, get: function () { return sfProject_1.SfProject; } });
+Object.defineProperty(exports, "SfProjectJson", { enumerable: true, get: function () { return sfProject_1.SfProjectJson; } });
 var validator_1 = require("./schema/validator");
 Object.defineProperty(exports, "SchemaValidator", { enumerable: true, get: function () { return validator_1.SchemaValidator; } });
-var sfdxError_1 = require("./sfdxError");
-Object.defineProperty(exports, "SfdxError", { enumerable: true, get: function () { return sfdxError_1.SfdxError; } });
+var printer_1 = require("./schema/printer");
+Object.defineProperty(exports, "SchemaPrinter", { enumerable: true, get: function () { return printer_1.SchemaPrinter; } });
+var sfError_1 = require("./sfError");
+Object.defineProperty(exports, "SfError", { enumerable: true, get: function () { return sfError_1.SfError; } });
 var pollingClient_1 = require("./status/pollingClient");
 Object.defineProperty(exports, "PollingClient", { enumerable: true, get: function () { return pollingClient_1.PollingClient; } });
 var streamingClient_1 = require("./status/streamingClient");
@@ -84,7 +100,15 @@ Object.defineProperty(exports, "REQUIRED_FIELDS", { enumerable: true, get: funct
 Object.defineProperty(exports, "User", { enumerable: true, get: function () { return user_1.User; } });
 var permissionSetAssignment_1 = require("./org/permissionSetAssignment");
 Object.defineProperty(exports, "PermissionSetAssignment", { enumerable: true, get: function () { return permissionSetAssignment_1.PermissionSetAssignment; } });
+var scratchOrgCreate_1 = require("./org/scratchOrgCreate");
+Object.defineProperty(exports, "scratchOrgCreate", { enumerable: true, get: function () { return scratchOrgCreate_1.scratchOrgCreate; } });
+Object.defineProperty(exports, "scratchOrgResume", { enumerable: true, get: function () { return scratchOrgCreate_1.scratchOrgResume; } });
+var scratchOrgLifecycleEvents_1 = require("./org/scratchOrgLifecycleEvents");
+Object.defineProperty(exports, "scratchOrgLifecycleEventName", { enumerable: true, get: function () { return scratchOrgLifecycleEvents_1.scratchOrgLifecycleEventName; } });
+Object.defineProperty(exports, "scratchOrgLifecycleStages", { enumerable: true, get: function () { return scratchOrgLifecycleEvents_1.scratchOrgLifecycleStages; } });
+var scratchOrgCache_1 = require("./org/scratchOrgCache");
+Object.defineProperty(exports, "ScratchOrgCache", { enumerable: true, get: function () { return scratchOrgCache_1.ScratchOrgCache; } });
 // Utility sub-modules
-__exportStar(require("./util/fs"), exports);
 __exportStar(require("./util/sfdc"), exports);
+__exportStar(require("./util/sfdcUrl"), exports);
 //# sourceMappingURL=exported.js.map

package/lib/global.d.ts

@@ -14,6 +14,12 @@ export declare enum Mode {
  * Global constants, methods, and configuration.
  */
 export declare class Global {
+    /**
+     * Enable interoperability between `.sfdx` and `.sf`.
+     *
+     * When @salesforce/core@v2 is deprecated and no longer used, this can be removed.
+     */
+    static SFDX_INTEROPERABILITY: boolean;
     /**
      * The global folder in which sfdx state is stored.
      */
@@ -22,18 +28,26 @@ export declare class Global {
      * The global folder in which sf state is stored.
      */
     static readonly SF_STATE_FOLDER = ".sf";
+    /**
+     * The preferred global folder in which state is stored.
+     */
+    static readonly STATE_FOLDER = ".sfdx";
     /**
      * The full system path to the global sfdx state folder.
      *
      * **See** {@link Global.SFDX_STATE_FOLDER}
      */
-    static readonly SFDX_DIR: string;
+    static get SFDX_DIR(): string;
     /**
      * The full system path to the global sf state folder.
      *
-     * **See** {@link Global.SF_STATE_FOLDER}
+     * **See**  {@link Global.SF_STATE_FOLDER}
+     */
+    static get SF_DIR(): string;
+    /**
+     * The full system path to the preferred global state folder
      */
-    static readonly SF_DIR: string;
+    static get DIR(): string;
     /**
      * The full system path to the global log file.
      */

package/lib/global.js

@@ -7,10 +7,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Global = exports.Mode = void 0;
+const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const kit_1 = require("@salesforce/kit");
-const fs_1 = require("./util/fs");
+const sfError_1 = require("./sfError");
 /**
  * Represents an environment mode.  Supports `production`, `development`, `demo`, and `test`
  * with the default mode being `production`.
@@ -28,6 +29,28 @@ var Mode;
  * Global constants, methods, and configuration.
  */
 class Global {
+    /**
+     * The full system path to the global sfdx state folder.
+     *
+     * **See** {@link Global.SFDX_STATE_FOLDER}
+     */
+    static get SFDX_DIR() {
+        return path.join(os.homedir(), Global.SFDX_STATE_FOLDER);
+    }
+    /**
+     * The full system path to the global sf state folder.
+     *
+     * **See**  {@link Global.SF_STATE_FOLDER}
+     */
+    static get SF_DIR() {
+        return path.join(os.homedir(), Global.SF_STATE_FOLDER);
+    }
+    /**
+     * The full system path to the preferred global state folder
+     */
+    static get DIR() {
+        return path.join(os.homedir(), Global.SFDX_STATE_FOLDER);
+    }
     /**
      * Gets the current mode environment variable as a {@link Mode} instance.
      *
@@ -46,10 +69,26 @@ class Global {
      */
     static async createDir(dirPath) {
         dirPath = dirPath ? path.join(Global.SFDX_DIR, dirPath) : Global.SFDX_DIR;
-        await fs_1.fs.mkdirp(dirPath, fs_1.fs.DEFAULT_USER_DIR_MODE);
+        try {
+            if (process.platform === 'win32') {
+                await fs.promises.mkdir(dirPath, { recursive: true });
+            }
+            else {
+                await fs.promises.mkdir(dirPath, { recursive: true, mode: 0o700 });
+            }
+        }
+        catch (error) {
+            throw new sfError_1.SfError(`Failed to create directory or set permissions for: ${dirPath}`);
+        }
     }
 }
 exports.Global = Global;
+/**
+ * Enable interoperability between `.sfdx` and `.sf`.
+ *
+ * When @salesforce/core@v2 is deprecated and no longer used, this can be removed.
+ */
+Global.SFDX_INTEROPERABILITY = kit_1.env.getBoolean('SF_SFDX_INTEROPERABILITY', true);
 /**
  * The global folder in which sfdx state is stored.
  */
@@ -59,19 +98,13 @@ Global.SFDX_STATE_FOLDER = '.sfdx';
  */
 Global.SF_STATE_FOLDER = '.sf';
 /**
- * The full system path to the global sfdx state folder.
- *
- * **See** {@link Global.SFDX_STATE_FOLDER}
- */
-Global.SFDX_DIR = path.join(os.homedir(), Global.SFDX_STATE_FOLDER);
-/**
- * The full system path to the global sf state folder.
- *
- * **See** {@link Global.SF_STATE_FOLDER}
+ * The preferred global folder in which state is stored.
  */
-Global.SF_DIR = path.join(os.homedir(), Global.SF_STATE_FOLDER);
+Global.STATE_FOLDER = Global.SFDX_STATE_FOLDER;
 /**
  * The full system path to the global log file.
  */
-Global.LOG_FILE_PATH = path.join(Global.SFDX_DIR, 'sfdx.log');
+// member ordering conflicts with the TS use-before-declaration error
+// eslint-disable-next-line @typescript-eslint/member-ordering
+Global.LOG_FILE_PATH = path.join(Global.SF_DIR, 'sf.log');
 //# sourceMappingURL=global.js.map

package/lib/lifecycleEvents.d.ts

@@ -1,5 +1,5 @@
 import { AnyJson } from '@salesforce/ts-types';
-declare type callback = (data: any) => Promise<void>;
+type callback = (data: any) => Promise<void>;
 /**
  * An asynchronous event listener and emitter that follows the singleton pattern. The singleton pattern allows lifecycle
  * events to be emitted from deep within a library and still be consumed by any other library or tool. It allows other
@@ -16,16 +16,29 @@ declare type callback = (data: any) => Promise<void>;
  *
  * // Deep in the deploy code, fire the event for all libraries and plugins to hear.
  * Lifecycle.getInstance().emit('deploy-metadata', metadataToBeDeployed);
+ *
+ * // if you don't need to await anything
+ * use `void Lifecycle.getInstance().emit('deploy-metadata', metadataToBeDeployed)` ;
  * ```
  */
 export declare class Lifecycle {
-    private debug;
     private readonly listeners;
+    static readonly telemetryEventName = "telemetry";
+    static readonly warningEventName = "warning";
+    private debug;
     private constructor();
+    /**
+     * return the package.json version of the sfdx-core library.
+     */
+    static staticVersion(): string;
     /**
      * Retrieve the singleton instance of this class so that all listeners and emitters can interact from any library or tool
      */
     static getInstance(): Lifecycle;
+    /**
+     * return the package.json version of the sfdx-core library.
+     */
+    version(): string;
     /**
      * Remove all listeners for a given event
      *
@@ -38,6 +51,18 @@ export declare class Lifecycle {
      * @param eventName The name of the event to get listeners of
      */
     getListeners(eventName: string): callback[];
+    /**
+     * Create a listener for the `telemetry` event
+     *
+     * @param cb The callback function to run when the event is emitted
+     */
+    onTelemetry(cb: (data: Record<string, unknown>) => Promise<void>): void;
+    /**
+     * Create a listener for the `warning` event
+     *
+     * @param cb The callback function to run when the event is emitted
+     */
+    onWarning(cb: (warning: string) => Promise<void>): void;
     /**
      * Create a new listener for a given event
      *
@@ -45,6 +70,18 @@ export declare class Lifecycle {
      * @param cb The callback function to run when the event is emitted
      */
     on<T = AnyJson>(eventName: string, cb: (data: T) => Promise<void>): void;
+    /**
+     * Emit a `telemetry` event, causing all callback functions to be run in the order they were registered
+     *
+     * @param data The data to emit
+     */
+    emitTelemetry(data: AnyJson): Promise<void>;
+    /**
+     * Emit a `warning` event, causing all callback functions to be run in the order they were registered
+     *
+     * @param data The warning (string) to emit
+     */
+    emitWarning(warning: string): Promise<void>;
     /**
      * Emit a given event, causing all callback functions to be run in the order they were registered
      *

package/lib/lifecycleEvents.js

@@ -8,6 +8,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Lifecycle = void 0;
 const Debug = require("debug");
+const semver_1 = require("semver");
+// needed for TS to not put everything inside /lib/src
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+const pjson = require("../package.json");
 /**
  * An asynchronous event listener and emitter that follows the singleton pattern. The singleton pattern allows lifecycle
  * events to be emitted from deep within a library and still be consumed by any other library or tool. It allows other
@@ -24,12 +29,21 @@ const Debug = require("debug");
  *
  * // Deep in the deploy code, fire the event for all libraries and plugins to hear.
  * Lifecycle.getInstance().emit('deploy-metadata', metadataToBeDeployed);
+ *
+ * // if you don't need to await anything
+ * use `void Lifecycle.getInstance().emit('deploy-metadata', metadataToBeDeployed)` ;
  * ```
  */
 class Lifecycle {
-    constructor() {
+    constructor(listeners = {}) {
+        this.listeners = listeners;
         this.debug = Debug(`sfdx:${this.constructor.name}`);
-        this.listeners = {};
+    }
+    /**
+     * return the package.json version of the sfdx-core library.
+     */
+    static staticVersion() {
+        return pjson.version;
     }
     /**
      * Retrieve the singleton instance of this class so that all listeners and emitters can interact from any library or tool
@@ -52,10 +66,30 @@ class Lifecycle {
         //
         // Nothing should EVER be removed, even across major versions.
         if (!global.salesforceCoreLifecycle) {
+            // it's not been loaded yet (basic singleton pattern)
             global.salesforceCoreLifecycle = new Lifecycle();
         }
+        else if (
+        // an older version was loaded that should be replaced
+        (0, semver_1.compare)(global.salesforceCoreLifecycle.version(), Lifecycle.staticVersion()) === -1) {
+            const oldInstance = global.salesforceCoreLifecycle;
+            // use the newer version and transfer any listeners from the old version
+            // object spread keeps them from being references
+            global.salesforceCoreLifecycle = new Lifecycle({ ...oldInstance.listeners });
+            // clean up any listeners on the old version
+            Object.keys(oldInstance.listeners).map((eventName) => {
+                oldInstance.removeAllListeners(eventName);
+            });
+        }
         return global.salesforceCoreLifecycle;
     }
+    /**
+     * return the package.json version of the sfdx-core library.
+     */
+    // eslint-disable-next-line class-methods-use-this
+    version() {
+        return pjson.version;
+    }
     /**
      * Remove all listeners for a given event
      *
@@ -79,6 +113,22 @@ class Lifecycle {
             return [];
         }
     }
+    /**
+     * Create a listener for the `telemetry` event
+     *
+     * @param cb The callback function to run when the event is emitted
+     */
+    onTelemetry(cb) {
+        this.on(Lifecycle.telemetryEventName, cb);
+    }
+    /**
+     * Create a listener for the `warning` event
+     *
+     * @param cb The callback function to run when the event is emitted
+     */
+    onWarning(cb) {
+        this.on(Lifecycle.warningEventName, cb);
+    }
     /**
      * Create a new listener for a given event
      *
@@ -93,6 +143,27 @@ class Lifecycle {
         listeners.push(cb);
         this.listeners[eventName] = listeners;
     }
+    /**
+     * Emit a `telemetry` event, causing all callback functions to be run in the order they were registered
+     *
+     * @param data The data to emit
+     */
+    async emitTelemetry(data) {
+        return this.emit(Lifecycle.telemetryEventName, data);
+    }
+    /**
+     * Emit a `warning` event, causing all callback functions to be run in the order they were registered
+     *
+     * @param data The warning (string) to emit
+     */
+    async emitWarning(warning) {
+        // if there are no listeners, warnings should go to the node process so they're not lost
+        // this also preserves behavior in UT where there's a spy on process.emitWarning
+        if (this.getListeners(Lifecycle.warningEventName).length === 0) {
+            process.emitWarning(warning);
+        }
+        return this.emit(Lifecycle.warningEventName, warning);
+    }
     /**
      * Emit a given event, causing all callback functions to be run in the order they were registered
      *
@@ -101,15 +172,18 @@ class Lifecycle {
      */
     async emit(eventName, data) {
         const listeners = this.getListeners(eventName);
-        if (listeners.length === 0) {
+        if (listeners.length === 0 && eventName !== Lifecycle.warningEventName) {
             this.debug(`A lifecycle event with the name ${eventName} does not exist. An event must be registered before it can be emitted.`);
         }
         else {
             for (const cb of listeners) {
+                // eslint-disable-next-line no-await-in-loop
                 await cb(data);
             }
         }
     }
 }
 exports.Lifecycle = Lifecycle;
+Lifecycle.telemetryEventName = 'telemetry';
+Lifecycle.warningEventName = 'warning';
 //# sourceMappingURL=lifecycleEvents.js.map

package/lib/logger.d.ts

@@ -6,7 +6,7 @@ import { Writable } from 'stream';
  * @param input The input to be serialized.
  * **See** {@link https://github.com/forcedotcom/node-bunyan#serializers|Bunyan Serializers API}
  */
-export declare type Serializer = (input: unknown) => unknown;
+export type Serializer = (input: unknown) => unknown;
 /**
  * A collection of named `Serializer`s.
  *
@@ -62,7 +62,7 @@ export declare enum LoggerLevel {
     FATAL = 60
 }
 /**
- *  `Logger` format types.
+ * `Logger` format types.
  */
 export declare enum LoggerFormat {
     JSON = 0,
@@ -99,7 +99,7 @@ export interface LoggerStream {
 /**
  * Any numeric `Logger` level.
  */
-export declare type LoggerLevelValue = LoggerLevel | number;
+export type LoggerLevelValue = LoggerLevel | number;
 /**
  * A collection of named `FieldValue`s.
  *
@@ -111,7 +111,7 @@ export interface Fields {
 /**
  * All possible field value types.
  */
-export declare type FieldValue = string | number | boolean;
+export type FieldValue = string | number | boolean;
 /**
  * Log line interface
  */
@@ -144,13 +144,13 @@ export interface LogLine {
  * ```
  * **See** https://github.com/forcedotcom/node-bunyan
  *
- * **See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_log_messages.htm
+ * **See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm
  */
 export declare class Logger {
     /**
      * The name of the root sfdx `Logger`.
      */
-    static readonly ROOT_NAME = "sfdx";
+    static readonly ROOT_NAME = "sf";
     /**
      * The default `LoggerLevel` when constructing new `Logger` instances.
      */
@@ -163,6 +163,17 @@ export declare class Logger {
     static readonly LEVEL_NAMES: string[];
     private static readonly lifecycle;
     private static rootLogger?;
+    /**
+     * The default rotation period for logs. Example '1d' will rotate logs daily (at midnight).
+     * See 'period' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file
+     */
+    readonly logRotationPeriod: string;
+    /**
+     * The number of backup rotated log files to keep.
+     * Example: '3' will have the base sf.log file, and the past 3 (period) log files.
+     * See 'count' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file
+     */
+    readonly logRotationCount: number;
     /**
      * Whether debug is enabled for this Logger.
      */
@@ -174,7 +185,7 @@ export declare class Logger {
      *
      * @param optionsOrName A set of `LoggerOptions` or name to use with the default options.
      *
-     * **Throws** *{@link SfdxError}{ name: 'RedundantRootLoggerError' }* More than one attempt is made to construct the root
+     * **Throws** *{@link SfError}{ name: 'RedundantRootLoggerError' }* More than one attempt is made to construct the root
      * `Logger`.
      */
     constructor(optionsOrName: LoggerOptions | string);
@@ -211,7 +222,7 @@ export declare class Logger {
      *
      * @param {string} levelName The level name to convert to a `LoggerLevel` enum value.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnrecognizedLoggerLevelNameError' }* The level name was not case-insensitively recognized as a valid `LoggerLevel` value.
+     * **Throws** *{@link SfError}{ name: 'UnrecognizedLoggerLevelNameError' }* The level name was not case-insensitively recognized as a valid `LoggerLevel` value.
      * @see {@Link LoggerLevel}
      */
     static getLevelByName(levelName: string): LoggerLevelValue;
@@ -249,7 +260,7 @@ export declare class Logger {
      *
      * @param {LoggerLevelValue} [level] The logger level.
      *
-     * **Throws** *{@link SfdxError}{ name: 'UnrecognizedLoggerLevelNameError' }* A value of `level` read from `SFDX_LOG_LEVEL`
+     * **Throws** *{@link SfError}{ name: 'UnrecognizedLoggerLevelNameError' }* A value of `level` read from `SFDX_LOG_LEVEL`
      * was invalid.
      *
      * ```
@@ -299,8 +310,7 @@ export declare class Logger {
     /**
      * Close the logger, including any streams, and remove all listeners.
      *
-     * @param fn A function with signature `(stream: LoggerStream) => void` to call for each stream with
-     *                        the stream as an arg.
+     * @param fn A function with signature `(stream: LoggerStream) => void` to call for each stream with the stream as an arg.
      */
     close(fn?: (stream: LoggerStream) => void): void;
     /**