@salesforce/core 4.0.0 → 4.0.1

package/lib/org/org.js

@@ -5,42 +5,30 @@
  * 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
  */
+/* eslint-disable class-methods-use-this */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Org = exports.SandboxEvents = exports.OrgTypes = void 0;
+exports.Org = exports.sandboxIsResumable = exports.SandboxEvents = exports.OrgTypes = 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 config_1 = require("../config/config");
 const configAggregator_1 = require("../config/configAggregator");
 const orgUsersConfig_1 = require("../config/orgUsersConfig");
-const sandboxOrgConfig_1 = require("../config/sandboxOrgConfig");
 const global_1 = require("../global");
 const lifecycleEvents_1 = require("../lifecycleEvents");
 const logger_1 = require("../logger");
-const sfdxError_1 = require("../sfdxError");
-const fs_1 = require("../util/fs");
+const sfError_1 = require("../sfError");
 const sfdc_1 = require("../util/sfdc");
 const webOAuthServer_1 = require("../webOAuthServer");
 const messages_1 = require("../messages");
-const globalInfo_1 = require("../globalInfo");
+const stateAggregator_1 = require("../stateAggregator");
+const pollingClient_1 = require("../status/pollingClient");
 const connection_1 = require("./connection");
 const authInfo_1 = require("./authInfo");
 const scratchOrgCreate_1 = require("./scratchOrgCreate");
 const orgConfigProperties_1 = require("./orgConfigProperties");
-messages_1.Messages.importMessagesDirectory(__dirname);
-const messages = messages_1.Messages.load('@salesforce/core', 'org', [
-    'deleteOrgHubError',
-    'insufficientAccessToDelete',
-    'missingAuthUsername',
-    'noDevHubFound',
-    'notADevHub',
-    'noUsernameFound',
-    'orgPollingTimeout',
-    'sandboxDeleteFailed',
-    'sandboxInfoCreateFailed',
-    'sandboxNotFound',
-    'scratchOrgNotFound',
-]);
+const messages = new messages_1.Messages('@salesforce/core', 'org', new Map([["notADevHub", "The provided dev hub username %s is not a valid dev hub."], ["noUsernameFound", "No username found."], ["noDevHubFound", "Unable to associate this scratch org with a DevHub."], ["deleteOrgHubError", "The Dev Hub org cannot be deleted."], ["insufficientAccessToDelete", "You do not have the appropriate permissions to delete a scratch org. Please contact your Salesforce admin."], ["scratchOrgNotFound", "Attempting to delete an expired or deleted org"], ["sandboxDeleteFailed", "The sandbox org deletion failed with a result of %s."], ["sandboxNotFound", "We can't find a SandboxProcess for the sandbox %s."], ["sandboxInfoCreateFailed", "The sandbox org creation failed with a result of %s."], ["missingAuthUsername", "The sandbox %s does not have an authorized username."], ["orgPollingTimeout", "Sandbox status is %s; timed out waiting for completion."], ["NotFoundOnDevHub", "The scratch org does not belong to the dev hub username %s."], ["AuthInfoOrgIdUndefined", "AuthInfo orgId is undefined."], ["sandboxCreateNotComplete", "The sandbox creation has not completed."], ["SandboxProcessNotFoundBySandboxName", "We can't find a SandboxProcess with the SandboxName %s."], ["MultiSandboxProcessNotFoundBySandboxName", "We found more than one SandboxProcess with the SandboxName %s."], ["sandboxNotResumable", "The sandbox %s cannot resume with status of %s."]]));
 var OrgTypes;
 (function (OrgTypes) {
     OrgTypes["Scratch"] = "scratch";
@@ -52,7 +40,13 @@ var SandboxEvents;
     SandboxEvents["EVENT_ASYNC_RESULT"] = "asyncResult";
     SandboxEvents["EVENT_RESULT"] = "result";
     SandboxEvents["EVENT_AUTH"] = "auth";
+    SandboxEvents["EVENT_RESUME"] = "resume";
 })(SandboxEvents = exports.SandboxEvents || (exports.SandboxEvents = {}));
+const resumableSandboxStatus = ['Activating', 'Pending', 'Pending Activation', 'Processing', 'Sampling', 'Completed'];
+function sandboxIsResumable(value) {
+    return resumableSandboxStatus.includes(value);
+}
+exports.sandboxIsResumable = sandboxIsResumable;
 /**
  * Provides a way to manage a locally authenticated Org.
  *
@@ -86,7 +80,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
     constructor(options) {
         super(options);
         this.status = Org.Status.UNKNOWN;
-        this.options = options || {};
+        this.options = options ?? {};
     }
     /**
      * create a sandbox from a production org
@@ -95,23 +89,105 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * @param sandboxReq SandboxRequest options to create the sandbox with
      * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
      */
-    async createSandbox(sandboxReq, options) {
-        var _a;
-        this.logger.debug('CreateSandbox called with SandboxRequest: %s ', sandboxReq);
+    async createSandbox(sandboxReq, options = {
+        wait: kit_1.Duration.minutes(6),
+        async: false,
+        interval: kit_1.Duration.seconds(30),
+    }) {
+        this.logger.debug(`CreateSandbox called with SandboxRequest: ${JSON.stringify(sandboxReq, undefined, 2)}`);
         const createResult = await this.connection.tooling.create('SandboxInfo', sandboxReq);
-        this.logger.debug('Return from calling tooling.create: %s ', createResult);
+        this.logger.debug(`Return from calling tooling.create: ${JSON.stringify(createResult, undefined, 2)}`);
         if (Array.isArray(createResult) || !createResult.success) {
             throw messages.createError('sandboxInfoCreateFailed', [JSON.stringify(createResult)]);
         }
-        const sandboxCreationProgress = await this.querySandboxProcess(createResult.id);
-        this.logger.debug('Return from calling singleRecordQuery with tooling: %s', sandboxCreationProgress);
-        const retries = options.wait ? options.wait.seconds / kit_1.Duration.seconds(30).seconds : 0;
-        this.logger.debug('pollStatusAndAuth sandboxProcessObj %s, maxPollingRetries %i', sandboxCreationProgress, retries);
-        const pollInterval = (_a = options.interval) !== null && _a !== void 0 ? _a : kit_1.Duration.seconds(30);
+        const sandboxCreationProgress = await this.querySandboxProcessBySandboxInfoId(createResult.id);
+        this.logger.debug(`Return from calling singleRecordQuery with tooling: ${JSON.stringify(sandboxCreationProgress, undefined, 2)}`);
+        const isAsync = !!options.async;
+        if (isAsync) {
+            // The user didn't want us to poll, so simply return the status
+            await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_ASYNC_RESULT, sandboxCreationProgress);
+            return sandboxCreationProgress;
+        }
+        const [wait, pollInterval] = this.validateWaitOptions(options);
+        this.logger.debug(`create - pollStatusAndAuth sandboxProcessObj ${JSON.stringify(sandboxCreationProgress, undefined, 2)}, max wait time of ${wait.minutes} minutes`);
         return this.pollStatusAndAuth({
             sandboxProcessObj: sandboxCreationProgress,
-            retries,
-            shouldPoll: retries > 0,
+            wait,
+            pollInterval,
+        });
+    }
+    /**
+     *
+     * @param sandboxReq SandboxRequest options to create the sandbox with
+     * @param sourceSandboxName the name of the sandbox that your new sandbox will be based on
+     * @param options Wait: The amount of time to wait before timing out, defaults to 0, Interval: The time interval between polling defaults to 30 seconds
+     * @returns {SandboxProcessObject} the newly created sandbox process object
+     */
+    async cloneSandbox(sandboxReq, sourceSandboxName, options) {
+        sandboxReq.SourceId = (await this.querySandboxProcessBySandboxName(sourceSandboxName)).SandboxInfoId;
+        this.logger.debug('Clone sandbox sourceId %s', sandboxReq.SourceId);
+        return this.createSandbox(sandboxReq, options);
+    }
+    /**
+     * resume a sandbox creation from a production org
+     * 'this' needs to be a production org with sandbox licenses available
+     *
+     * @param resumeSandboxRequest SandboxRequest options to create the sandbox with
+     * @param options Wait: The amount of time to wait (default: 30 minutes) before timing out,
+     * Interval: The time interval (default: 30 seconds) between polling
+     */
+    async resumeSandbox(resumeSandboxRequest, options = {
+        wait: kit_1.Duration.minutes(0),
+        async: false,
+        interval: kit_1.Duration.seconds(30),
+    }) {
+        this.logger.debug(`ResumeSandbox called with ResumeSandboxRequest: ${JSON.stringify(resumeSandboxRequest, undefined, 2)}`);
+        let sandboxCreationProgress;
+        // seed the sandboxCreationProgress via the resumeSandboxRequest options
+        if (resumeSandboxRequest.SandboxName) {
+            sandboxCreationProgress = await this.querySandboxProcessBySandboxName(resumeSandboxRequest.SandboxName);
+        }
+        else if (resumeSandboxRequest.SandboxProcessObjId) {
+            sandboxCreationProgress = await this.querySandboxProcessById(resumeSandboxRequest.SandboxProcessObjId);
+        }
+        else {
+            throw messages.createError('sandboxNotFound', [
+                resumeSandboxRequest.SandboxName ?? resumeSandboxRequest.SandboxProcessObjId,
+            ]);
+        }
+        this.logger.debug(`Return from calling singleRecordQuery with tooling: ${JSON.stringify(sandboxCreationProgress, undefined, 2)}`);
+        if (!sandboxIsResumable(sandboxCreationProgress.Status)) {
+            throw messages.createError('sandboxNotResumable', [
+                sandboxCreationProgress.SandboxName,
+                sandboxCreationProgress.Status,
+            ]);
+        }
+        await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_RESUME, sandboxCreationProgress);
+        const [wait, pollInterval] = this.validateWaitOptions(options);
+        // if wait is 0, return the sandboxCreationProgress immediately
+        if (wait.seconds === 0) {
+            if (sandboxCreationProgress.Status === 'Completed') {
+                // check to see if sandbox can authenticate via sandboxAuth endpoint
+                const sandboxInfo = await this.sandboxSignupComplete(sandboxCreationProgress);
+                if (sandboxInfo) {
+                    await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_AUTH, sandboxInfo);
+                    try {
+                        this.logger.debug(`sandbox signup complete with ${JSON.stringify(sandboxInfo, undefined, 2)}`);
+                        await this.writeSandboxAuthFile(sandboxCreationProgress, sandboxInfo);
+                        return sandboxCreationProgress;
+                    }
+                    catch (err) {
+                        // eat the error, we don't want to throw an error if we can't write the file
+                    }
+                }
+            }
+            await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_ASYNC_RESULT, sandboxCreationProgress);
+            throw messages.createError('sandboxCreateNotComplete');
+        }
+        this.logger.debug(`resume - pollStatusAndAuth sandboxProcessObj ${JSON.stringify(sandboxCreationProgress, undefined, 2)}, max wait time of ${wait.minutes} minutes`);
+        return this.pollStatusAndAuth({
+            sandboxProcessObj: sandboxCreationProgress,
+            wait,
             pollInterval,
         });
     }
@@ -125,6 +201,16 @@ class Org extends kit_1.AsyncOptionalCreatable {
     async scratchOrgCreate(options) {
         return (0, scratchOrgCreate_1.scratchOrgCreate)({ ...options, hubOrg: this });
     }
+    /**
+     * Reports sandbox org creation status. If the org is ready, authenticates to the org.
+     *
+     * @param {sandboxname} string the sandbox name
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     * @returns {SandboxProcessObject} the sandbox process object
+     */
+    async sandboxStatus(sandboxname, options) {
+        return this.authWithRetriesByName(sandboxname, options);
+    }
     /**
      * Clean all data files in the org's data path. Usually <workspace>/.sfdx/orgs/<username>.
      *
@@ -134,8 +220,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
     async cleanLocalOrgData(orgDataPath, throwWhenRemoveFails = false) {
         let dataPath;
         try {
-            const rootFolder = await config_1.Config.resolveRootFolder(false);
-            dataPath = (0, path_1.join)(rootFolder, global_1.Global.SFDX_STATE_FOLDER, orgDataPath ? orgDataPath : 'orgs');
+            dataPath = await this.getLocalDataDir(orgDataPath);
             this.logger.debug(`cleaning data for path: ${dataPath}`);
         }
         catch (err) {
@@ -147,18 +232,16 @@ class Org extends kit_1.AsyncOptionalCreatable {
             }
             throw err;
         }
-        return this.manageDelete(async () => await fs_1.fs.remove(dataPath), dataPath, throwWhenRemoveFails);
+        return this.manageDelete(async () => fs.promises.rmdir(dataPath), dataPath, throwWhenRemoveFails);
     }
     /**
      * @ignore
      */
     async retrieveOrgUsersConfig() {
-        return await orgUsersConfig_1.OrgUsersConfig.create(orgUsersConfig_1.OrgUsersConfig.getOptions(this.getOrgId()));
+        return orgUsersConfig_1.OrgUsersConfig.create(orgUsersConfig_1.OrgUsersConfig.getOptions(this.getOrgId()));
     }
     /**
-     * Removes the scratch org config file at $HOME/.sfdx/[name].json, any project level org
-     * files, all user auth files for the org, matching default config settings, and any
-     * matching aliases.
+     * Cleans up all org related artifacts including users, sandbox config (if a sandbox), source tracking files, and auth file.
      *
      * @param throwWhenRemoveFails Determines if the call should throw an error or fail silently.
      */
@@ -168,7 +251,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
         if (this.getConnection().isUsingAccessToken()) {
             return Promise.resolve();
         }
-        await this.removeSandboxConfig(throwWhenRemoveFails);
+        await this.removeSandboxConfig();
         await this.removeUsers(throwWhenRemoveFails);
         await this.removeUsersConfig();
         // An attempt to remove this org's auth file occurs in this.removeUsersConfig. That's because this org's usersname is also
@@ -176,20 +259,21 @@ class Org extends kit_1.AsyncOptionalCreatable {
         //
         // So, just in case no users are added to this org we will try the remove again.
         await this.removeAuth();
+        await this.removeSourceTrackingFiles();
     }
     /**
      * Check if org is a sandbox org by checking its SandboxOrgConfig.
      *
      */
     async isSandbox() {
-        return !!(await this.getSandboxOrgConfigField(sandboxOrgConfig_1.SandboxOrgConfig.Fields.PROD_ORG_USERNAME));
+        return (await stateAggregator_1.StateAggregator.getInstance()).sandboxes.hasFile(this.getOrgId());
     }
     /**
      * Check that this org is a scratch org by asking the dev hub if it knows about it.
      *
-     * **Throws** *{@link SfdxError}{ name: 'NotADevHubError' }* Not a Dev Hub.
+     * **Throws** *{@link SfError}{ name: 'NotADevHubError' }* Not a Dev Hub.
      *
-     * **Throws** *{@link SfdxError}{ name: 'NoResultsError' }* No results.
+     * **Throws** *{@link SfError}{ name: 'NoResultsError' }* No results.
      *
      * @param devHubUsernameOrAlias The username or alias of the dev hub org.
      */
@@ -200,12 +284,12 @@ class Org extends kit_1.AsyncOptionalCreatable {
         }
         const devHubConnection = (await Org.create({ aliasOrUsername })).getConnection();
         const thisOrgAuthConfig = this.getConnection().getAuthInfoFields();
-        const trimmedId = sfdc_1.sfdc.trimTo15(thisOrgAuthConfig.orgId);
+        const trimmedId = (0, sfdc_1.trimTo15)(thisOrgAuthConfig.orgId);
         const DEV_HUB_SOQL = `SELECT CreatedDate,Edition,ExpirationDate FROM ActiveScratchOrg WHERE ScratchOrg='${trimmedId}'`;
         try {
             const results = await devHubConnection.query(DEV_HUB_SOQL);
-            if ((0, ts_types_1.getNumber)(results, 'records.length') !== 1) {
-                throw new sfdxError_1.SfdxError('No results', 'NoResultsError');
+            if (results.records.length !== 1) {
+                throw new sfError_1.SfError('No results', 'NoResultsError');
             }
         }
         catch (err) {
@@ -329,6 +413,45 @@ class Org extends kit_1.AsyncOptionalCreatable {
             return false;
         }
     }
+    /**
+     * Returns `true` if the org uses source tracking.
+     * Side effect: updates files where the property doesn't currently exist
+     */
+    async tracksSource() {
+        // use the property if it exists
+        const tracksSource = this.getField(Org.Fields.TRACKS_SOURCE);
+        if ((0, ts_types_1.isBoolean)(tracksSource)) {
+            return tracksSource;
+        }
+        // scratch orgs with no property use tracking by default
+        if (await this.determineIfScratch()) {
+            // save true for next time to avoid checking again
+            await this.setTracksSource(true);
+            return true;
+        }
+        if (await this.determineIfSandbox()) {
+            // does the sandbox know about the SourceMember object?
+            const supportsSourceMembers = await this.supportsSourceTracking();
+            await this.setTracksSource(supportsSourceMembers);
+            return supportsSourceMembers;
+        }
+        // any other non-sandbox, non-scratch orgs won't use tracking
+        await this.setTracksSource(false);
+        return false;
+    }
+    /**
+     * Set the tracking property on the org's auth file
+     *
+     * @param value true or false (whether the org should use source tracking or not)
+     */
+    async setTracksSource(value) {
+        const originalAuth = await authInfo_1.AuthInfo.create({ username: this.getUsername() });
+        return originalAuth.handleAliasAndDefaultSettings({
+            setDefault: false,
+            setDefaultDevHub: false,
+            setTracksSource: value,
+        });
+    }
     /**
      * Returns `true` if the org is a scratch org.
      *
@@ -376,10 +499,10 @@ class Org extends kit_1.AsyncOptionalCreatable {
         const username = this.getUsername();
         if (username) {
             const organization = await this.retrieveOrganizationInformation();
-            const isScratch = organization.IsSandbox && organization.TrialExpirationDate;
+            const isScratch = organization.IsSandbox && Boolean(organization.TrialExpirationDate);
             const isSandbox = organization.IsSandbox && !organization.TrialExpirationDate;
-            const info = await globalInfo_1.GlobalInfo.getInstance();
-            info.orgs.update(username, {
+            const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
+            stateAggregator.orgs.update(username, {
                 [Org.Fields.NAME]: organization.Name,
                 [Org.Fields.INSTANCE_NAME]: organization.InstanceName,
                 [Org.Fields.NAMESPACE_PREFIX]: organization.NamespacePrefix,
@@ -387,7 +510,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 [Org.Fields.IS_SCRATCH]: isScratch,
                 [Org.Fields.TRIAL_EXPIRATION_DATE]: organization.TrialExpirationDate,
             });
-            await info.write();
+            await stateAggregator.orgs.write(username);
         }
     }
     /**
@@ -409,7 +532,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
         const config = await this.retrieveOrgUsersConfig();
         const contents = await config.read();
         const thisUsername = (0, ts_types_1.ensure)(this.getUsername());
-        const usernames = (0, ts_types_1.ensureJsonArray)(contents.usernames || [thisUsername]);
+        const usernames = (0, ts_types_1.ensureJsonArray)(contents.usernames ?? [thisUsername]);
         return Promise.all(usernames.map((username) => {
             if (username === thisUsername) {
                 return authInfo_1.AuthInfo.create({
@@ -440,7 +563,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
      */
     async addUsername(auth) {
         if (!auth) {
-            throw new sfdxError_1.SfdxError('Missing auth info', 'MissingAuthInfo');
+            throw new sfError_1.SfError('Missing auth info', 'MissingAuthInfo');
         }
         const authInfo = (0, ts_types_1.isString)(auth) ? await authInfo_1.AuthInfo.create({ username: auth }) : auth;
         this.logger.debug(`adding username ${authInfo.getFields().username}`);
@@ -448,9 +571,9 @@ class Org extends kit_1.AsyncOptionalCreatable {
         const contents = await orgConfig.read();
         // TODO: This is kind of screwy because contents values can be `AnyJson | object`...
         // needs config refactoring to improve
-        const usernames = contents.usernames || [];
+        const usernames = contents.usernames ?? [];
         if (!(0, ts_types_1.isArray)(usernames)) {
-            throw new sfdxError_1.SfdxError('Usernames is not an array', 'UnexpectedDataFormat');
+            throw new sfError_1.SfError('Usernames is not an array', 'UnexpectedDataFormat');
         }
         let shouldUpdate = false;
         const thisUsername = (0, ts_types_1.ensure)(this.getUsername());
@@ -472,44 +595,41 @@ class Org extends kit_1.AsyncOptionalCreatable {
     /**
      * Removes a username from the user config for this object. For convenience `this` object is returned.
      *
-     * **Throws** *{@link SfdxError}{ name: 'MissingAuthInfoError' }* Auth info is missing.
+     * **Throws** *{@link SfError}{ name: 'MissingAuthInfoError' }* Auth info is missing.
      *
      * @param {AuthInfo | string} auth The AuthInfo containing the username to remove.
      */
     async removeUsername(auth) {
         if (!auth) {
-            throw new sfdxError_1.SfdxError('Missing auth info', 'MissingAuthInfoError');
+            throw new sfError_1.SfError('Missing auth info', 'MissingAuthInfoError');
         }
         const authInfo = (0, ts_types_1.isString)(auth) ? await authInfo_1.AuthInfo.create({ username: auth }) : auth;
         this.logger.debug(`removing username ${authInfo.getFields().username}`);
         const orgConfig = await this.retrieveOrgUsersConfig();
         const contents = await orgConfig.read();
         const targetUser = authInfo.getFields().username;
-        const usernames = (contents.usernames || []);
+        const usernames = (contents.usernames ?? []);
         contents.usernames = usernames.filter((username) => username !== targetUser);
         await orgConfig.write();
         return this;
     }
     /**
-     * Sets the key/value pair in the sandbox config for this org. For convenience `this` object is returned.
+     * set the sandbox config related to this given org
      *
-     *
-     * @param {key} The key for this value
-     * @param {value} The value to save
+     * @param orgId {string} orgId of the sandbox
+     * @param config {SandboxFields} config of the sandbox
      */
-    async setSandboxOrgConfigField(field, value) {
-        const sandboxOrgConfig = await this.retrieveSandboxOrgConfig();
-        sandboxOrgConfig.set(field, value);
-        await sandboxOrgConfig.write();
+    async setSandboxConfig(orgId, config) {
+        (await stateAggregator_1.StateAggregator.getInstance()).sandboxes.set(orgId, config);
         return this;
     }
     /**
-     * Returns an org config field. Returns undefined if the field is not set or invalid.
+     * get the sandbox config for the given orgId
+     *
+     * @param orgId {string} orgId of the sandbox
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async getSandboxOrgConfigField(field) {
-        const sandboxOrgConfig = await this.retrieveSandboxOrgConfig();
-        return sandboxOrgConfig.get(field);
+    async getSandboxConfig(orgId) {
+        return (await stateAggregator_1.StateAggregator.getInstance()).sandboxes.read(orgId);
     }
     /**
      * Retrieves the highest api version that is supported by the target server instance. If the apiVersion configured for
@@ -517,7 +637,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * results in a warning.
      */
     async retrieveMaxApiVersion() {
-        return await this.getConnection().retrieveMaxApiVersion();
+        return this.getConnection().retrieveMaxApiVersion();
     }
     /**
      * Returns the admin username used to create the org.
@@ -529,7 +649,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * Returns the orgId for this org.
      */
     getOrgId() {
-        return this.orgId || this.getField(Org.Fields.ORG_ID);
+        return this.orgId ?? this.getField(Org.Fields.ORG_ID);
     }
     /**
      * Returns for the config aggregator.
@@ -541,14 +661,14 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * Returns an org field. Returns undefined if the field is not set or invalid.
      */
     getField(key) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        /* eslint-disable @typescript-eslint/ban-ts-comment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
         // @ts-ignore Legacy. We really shouldn't be doing this.
         const ownProp = this[key];
         if (ownProp && typeof ownProp !== 'function')
             return ownProp;
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
         // @ts-ignore
         return this.getConnection().getAuthInfoFields()[key];
+        /* eslint-enable @typescript-eslint/ban-ts-comment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
     }
     /**
      * Returns a map of requested fields.
@@ -562,15 +682,69 @@ class Org extends kit_1.AsyncOptionalCreatable {
     }
     /**
      * Returns the JSForce connection for the org.
+     * side effect: If you pass it an apiVersion, it will set it on the Org
+     * so that future calls to getConnection() will also use that version.
+     *
+     * @param apiVersion The API version to use for the connection.
      */
-    getConnection() {
+    getConnection(apiVersion) {
+        if (apiVersion) {
+            if (this.connection.getApiVersion() === apiVersion) {
+                this.logger.warn(`Default API version is already ${apiVersion}`);
+            }
+            else {
+                this.connection.setApiVersion(apiVersion);
+            }
+        }
         return this.connection;
     }
+    async supportsSourceTracking() {
+        if (this.isScratch()) {
+            return true;
+        }
+        try {
+            await this.getConnection().tooling.sobject('SourceMember').describe();
+            return true;
+        }
+        catch (err) {
+            if (err.message.includes('The requested resource does not exist')) {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /**
+     * query SandboxProcess via sandbox name
+     *
+     * @param name SandboxName to query for
+     * @private
+     */
+    async querySandboxProcessBySandboxName(name) {
+        return this.querySandboxProcess(`SandboxName='${name}'`);
+    }
+    /**
+     * query SandboxProcess via SandboxInfoId
+     *
+     * @param id SandboxInfoId to query for
+     * @private
+     */
+    async querySandboxProcessBySandboxInfoId(id) {
+        return this.querySandboxProcess(`SandboxInfoId='${id}'`);
+    }
+    /**
+     * query SandboxProcess via Id
+     *
+     * @param id SandboxProcessId to query for
+     * @private
+     */
+    async querySandboxProcessById(id) {
+        return this.querySandboxProcess(`Id='${id}'`);
+    }
     /**
      * Initialize async components.
      */
     async init() {
-        const globalInfo = await globalInfo_1.GlobalInfo.getInstance();
+        const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
         this.logger = await logger_1.Logger.child('Org');
         this.configAggregator = this.options.aggregator ? this.options.aggregator : await configAggregator_1.ConfigAggregator.create();
         if (!this.options.connection) {
@@ -579,14 +753,14 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 const aliasOrUsername = this.options.isDevHub
                     ? this.configAggregator.getPropertyValue(orgConfigProperties_1.OrgConfigProperties.TARGET_DEV_HUB)
                     : this.configAggregator.getPropertyValue(orgConfigProperties_1.OrgConfigProperties.TARGET_ORG);
-                this.options.aliasOrUsername = aliasOrUsername || undefined;
+                this.options.aliasOrUsername = aliasOrUsername ?? undefined;
             }
-            const username = globalInfo.aliases.resolveUsername(this.options.aliasOrUsername);
+            const username = stateAggregator.aliases.resolveUsername(this.options.aliasOrUsername);
             if (!username) {
                 throw messages.createError('noUsernameFound');
             }
             this.connection = await connection_1.Connection.create({
-                // If no username is provided or resolvable from an alias, AuthInfo will throw an SfdxError.
+                // If no username is provided or resolvable from an alias, AuthInfo will throw an SfError.
                 authInfo: await authInfo_1.AuthInfo.create({ username, isDevHub: this.options.isDevHub }),
             });
         }
@@ -596,11 +770,68 @@ class Org extends kit_1.AsyncOptionalCreatable {
         this.orgId = this.getField(Org.Fields.ORG_ID);
     }
     /**
-     * **Throws** *{@link SfdxError}{ name: 'NotSupportedError' }* Throws an unsupported error.
+     * **Throws** *{@link SfError}{ name: 'NotSupportedError' }* Throws an unsupported error.
      */
+    // eslint-disable-next-line class-methods-use-this
     getDefaultOptions() {
-        throw new sfdxError_1.SfdxError('Not Supported', 'NotSupportedError');
+        throw new sfError_1.SfError('Not Supported', 'NotSupportedError');
+    }
+    async getLocalDataDir(orgDataPath) {
+        const rootFolder = await config_1.Config.resolveRootFolder(false);
+        return (0, path_1.join)(rootFolder, global_1.Global.SFDX_STATE_FOLDER, orgDataPath ? orgDataPath : 'orgs');
     }
+    /**
+     * Gets the sandboxProcessObject and then polls for it to complete.
+     *
+     * @param sandboxProcessName sanbox process name
+     * @param options { wait?: Duration; interval?: Duration }
+     * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
+     */
+    async authWithRetriesByName(sandboxProcessName, options) {
+        return this.authWithRetries(await this.queryLatestSandboxProcessBySandboxName(sandboxProcessName), options);
+    }
+    /**
+     * Polls the sandbox org for the sandboxProcessObject.
+     *
+     * @param sandboxProcessObj: The in-progress sandbox signup request
+     * @param options { wait?: Duration; interval?: Duration }
+     * @returns {SandboxProcessObject}
+     */
+    async authWithRetries(sandboxProcessObj, options = {
+        wait: kit_1.Duration.minutes(0),
+        interval: kit_1.Duration.seconds(30),
+    }) {
+        const [wait, pollInterval] = this.validateWaitOptions(options);
+        this.logger.debug(`AuthWithRetries sandboxProcessObj ${JSON.stringify(sandboxProcessObj, undefined, 2)}, max wait time of ${wait.minutes} minutes`);
+        return this.pollStatusAndAuth({
+            sandboxProcessObj,
+            wait,
+            pollInterval,
+        });
+    }
+    /**
+     * Query the sandbox for the SandboxProcessObject by sandbox name
+     *
+     * @param sandboxName The name of the sandbox to query
+     * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
+     */
+    async queryLatestSandboxProcessBySandboxName(sandboxNameIn) {
+        const { tooling } = this.getConnection();
+        this.logger.debug('QueryLatestSandboxProcessBySandboxName called with SandboxName: %s ', sandboxNameIn);
+        const queryStr = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE SandboxName='${sandboxNameIn}' AND Status != 'D' ORDER BY CreatedDate DESC LIMIT 1`;
+        const queryResult = await tooling.query(queryStr);
+        this.logger.debug('Return from calling queryToolingApi: %s ', queryResult);
+        if (queryResult?.records?.length === 1) {
+            return queryResult.records[0];
+        }
+        else if (queryResult.records && queryResult.records.length > 1) {
+            throw messages.createError('MultiSandboxProcessNotFoundBySandboxName', [sandboxNameIn]);
+        }
+        else {
+            throw messages.createError('SandboxProcessNotFoundBySandboxName', [sandboxNameIn]);
+        }
+    }
+    // eslint-disable-next-line class-methods-use-this
     async queryProduction(org, field, value) {
         return org.connection.singleRecordQuery(`SELECT SandboxInfoId FROM SandboxProcess WHERE ${field} ='${value}' AND Status NOT IN ('D', 'E')`, { tooling: true });
     }
@@ -617,47 +848,53 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * @private
      */
     async deleteSandbox(prodOrg) {
-        prodOrg !== null && prodOrg !== void 0 ? prodOrg : (prodOrg = await Org.create({
+        const sandbox = await this.getSandboxConfig(this.getOrgId());
+        prodOrg ??= await Org.create({
             aggregator: this.configAggregator,
-            aliasOrUsername: await this.getSandboxOrgConfigField(sandboxOrgConfig_1.SandboxOrgConfig.Fields.PROD_ORG_USERNAME),
-        }));
-        let result;
-        // attempt to locate sandbox id by username
-        try {
-            // try to calculate sandbox name from the production org
-            // production org: admin@integrationtesthub.org
-            // this.getUsername: admin@integrationtesthub.org.dev1
-            // sandboxName in Production: dev1
-            const sandboxName = (this.getUsername() || '').split(`${prodOrg.getUsername()}.`)[1];
-            if (!sandboxName) {
-                this.logger.debug('Could not construct a sandbox name');
-                throw new Error();
-            }
-            this.logger.debug(`attempting to locate sandbox with username ${sandboxName}`);
-            result = await this.queryProduction(prodOrg, 'SandboxName', sandboxName);
-            if (!result) {
-                this.logger.debug(`Failed to find sandbox with username: ${sandboxName}`);
-                throw new Error();
-            }
-        }
-        catch {
-            // if an error is thrown, don't panic yet. we'll try querying by orgId
-            const trimmedId = sfdc_1.sfdc.trimTo15(this.getOrgId());
-            this.logger.debug(`defaulting to trimming id from ${this.getOrgId()} to ${trimmedId}`);
+            aliasOrUsername: sandbox?.prodOrgUsername,
+        });
+        let sandboxInfoId = sandbox?.sandboxInfoId;
+        if (!sandboxInfoId) {
+            let result;
             try {
-                result = await this.queryProduction(prodOrg, 'SandboxOrganization', trimmedId);
+                // grab sandboxName from config or try to calculate from the sandbox username
+                const sandboxName = sandbox?.sandboxName ?? (this.getUsername() ?? '').split(`${prodOrg.getUsername()}.`)[1];
+                if (!sandboxName) {
+                    this.logger.debug('Sandbox name is not available');
+                    // jump to query by orgId
+                    throw new Error();
+                }
+                this.logger.debug(`attempting to locate sandbox with sandbox ${sandboxName}`);
+                try {
+                    result = await this.queryProduction(prodOrg, 'SandboxName', sandboxName);
+                }
+                catch (err) {
+                    this.logger.debug(`Failed to find sandbox with sandbox name: ${sandboxName}`);
+                    // jump to query by orgId
+                    throw err;
+                }
             }
             catch {
-                throw messages.createError('sandboxNotFound', [trimmedId]);
+                // if an error is thrown, don't panic yet. we'll try querying by orgId
+                const trimmedId = (0, sfdc_1.trimTo15)(this.getOrgId());
+                this.logger.debug(`defaulting to trimming id from ${this.getOrgId()} to ${trimmedId}`);
+                try {
+                    result = await this.queryProduction(prodOrg, 'SandboxOrganization', trimmedId);
+                    sandboxInfoId = result.SandboxInfoId;
+                }
+                catch {
+                    // eating exceptions when trying to find sandbox process record by orgId
+                    // allows idempotent cleanup of sandbox orgs
+                    this.logger.debug(`Failed find a SandboxProcess for the sandbox org: ${this.getOrgId()}`);
+                }
             }
         }
-        // const deleteResult = await prodOrg.connection.tooling.delete('SandboxInfo', result.SandboxInfoId);
-        const deleteResult = await this.destroySandbox(prodOrg, result.SandboxInfoId);
-        this.logger.debug('Return from calling tooling.delete: %o ', deleteResult);
-        await this.remove();
-        if (Array.isArray(deleteResult) || !deleteResult.success) {
-            throw messages.createError('sandboxDeleteFailed', [JSON.stringify(deleteResult)]);
+        if (sandboxInfoId) {
+            const deleteResult = await this.destroySandbox(prodOrg, sandboxInfoId);
+            this.logger.debug('Return from calling tooling.delete: ', deleteResult);
         }
+        // cleanup remaining artifacts
+        await this.remove();
     }
     /**
      * If this Org is a scratch org, calling this method will delete the scratch org from the DevHub and clean up any local files
@@ -667,7 +904,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
      */
     async deleteScratchOrg(devHub) {
         // if we didn't get a devHub, we'll get it from the this org
-        devHub !== null && devHub !== void 0 ? devHub : (devHub = await this.getDevHubOrg());
+        devHub ??= await this.getDevHubOrg();
         if (!devHub) {
             throw messages.createError('noDevHubFound');
         }
@@ -705,14 +942,14 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * this Org. You don't want to call this method directly. Instead consider calling Org.remove()
      */
     async removeAuth() {
-        const config = await globalInfo_1.GlobalInfo.getInstance();
+        const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
         const username = this.getUsername();
         // If there is no username, it has already been removed from the globalInfo.
         // We can skip the unset and just ensure that globalInfo is updated.
         if (username) {
             this.logger.debug(`Removing auth for user: ${username}`);
             this.logger.debug(`Clearing auth cache for user: ${username}`);
-            config.orgs.unset(username);
+            await stateAggregator.orgs.remove(username);
         }
     }
     /**
@@ -725,12 +962,6 @@ class Org extends kit_1.AsyncOptionalCreatable {
             await config.unlink();
         }
     }
-    /**
-     * @ignore
-     */
-    async retrieveSandboxOrgConfig() {
-        return await sandboxOrgConfig_1.SandboxOrgConfig.create(sandboxOrgConfig_1.SandboxOrgConfig.getOptions(this.getOrgId()));
-    }
     async manageDelete(cb, dirPath, throwWhenRemoveFails) {
         return cb().catch((e) => {
             if (throwWhenRemoveFails) {
@@ -749,7 +980,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
      */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     async removeUsers(throwWhenRemoveFails) {
-        const globalInfo = await globalInfo_1.GlobalInfo.getInstance();
+        const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
         this.logger.debug(`Removing users associate with org: ${this.getOrgId()}`);
         const config = await this.retrieveOrgUsersConfig();
         this.logger.debug(`using path for org users: ${config.getPath()}`);
@@ -757,8 +988,8 @@ class Org extends kit_1.AsyncOptionalCreatable {
         await Promise.all(authInfos
             .map((auth) => auth.getFields().username)
             .map(async (username) => {
-            const aliasKeys = (username && globalInfo.aliases.getAll(username)) || [];
-            globalInfo.aliases.unsetAll(username);
+            const aliasKeys = (username && stateAggregator.aliases.getAll(username)) ?? [];
+            stateAggregator.aliases.unsetAll(username);
             const orgForUser = username === this.getUsername()
                 ? this
                 : await Org.create({
@@ -773,24 +1004,17 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 needsConfigUpdate ? config_1.Config.update(configInfo.isGlobal(), orgType, undefined) : undefined,
             ].filter(Boolean);
         }));
-        await globalInfo.write();
+        await stateAggregator.aliases.write();
     }
-    /**
-     * Remove an associate sandbox config.
-     *
-     * @param throwWhenRemoveFails true if manageDelete should throw or not if the deleted fails.
-     */
-    async removeSandboxConfig(throwWhenRemoveFails) {
-        const sandboxOrgConfig = await this.retrieveSandboxOrgConfig();
-        if (await sandboxOrgConfig.exists()) {
-            await this.manageDelete(async () => await sandboxOrgConfig.unlink(), sandboxOrgConfig.getPath(), throwWhenRemoveFails);
-        }
+    async removeSandboxConfig() {
+        const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
+        await stateAggregator.sandboxes.remove(this.getOrgId());
     }
     async writeSandboxAuthFile(sandboxProcessObj, sandboxRes) {
-        this.logger.debug('writeSandboxAuthFile sandboxProcessObj: %s, sandboxRes: %s', sandboxProcessObj, sandboxRes);
+        this.logger.debug(`writeSandboxAuthFile sandboxProcessObj: ${JSON.stringify(sandboxProcessObj)}, sandboxRes: ${JSON.stringify(sandboxRes)}`);
         if (sandboxRes.authUserName) {
             const productionAuthFields = this.connection.getAuthInfoFields();
-            this.logger.debug('Result from getAuthInfoFields: AuthFields %s', productionAuthFields);
+            this.logger.debug('Result from getAuthInfoFields: AuthFields', productionAuthFields);
             // let's do headless auth via jwt (if we have privateKey) or web auth
             const oauth2Options = {
                 loginUrl: sandboxRes.loginUrl,
@@ -802,16 +1026,34 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 oauth2Options.redirectUri = `http://localhost:${await webOAuthServer_1.WebOAuthServer.determineOauthPort()}/OauthRedirect`;
                 oauth2Options.authCode = sandboxRes.authCode;
             }
+            else {
+                oauth2Options.privateKey = productionAuthFields.privateKey;
+                oauth2Options.clientId = productionAuthFields.clientId;
+            }
             const authInfo = await authInfo_1.AuthInfo.create({
                 username: sandboxRes.authUserName,
                 oauth2Options,
                 parentUsername: productionAuthFields.username,
             });
+            this.logger.debug('Creating AuthInfo for sandbox', sandboxRes.authUserName, productionAuthFields.username, oauth2Options);
+            // save auth info for new sandbox
             await authInfo.save();
-            const sandboxOrg = await Org.create({ aliasOrUsername: authInfo.getUsername() });
-            await sandboxOrg.setSandboxOrgConfigField(sandboxOrgConfig_1.SandboxOrgConfig.Fields.PROD_ORG_USERNAME, 
-            // we couldn't get this far into the process without a production org so username will be there
-            productionAuthFields.username);
+            const sandboxOrgId = authInfo.getFields().orgId;
+            if (!sandboxOrgId) {
+                throw messages.createError('AuthInfoOrgIdUndefined');
+            }
+            // set the sandbox config value
+            const sfSandbox = {
+                sandboxUsername: sandboxRes.authUserName,
+                sandboxOrgId,
+                prodOrgUsername: this.getUsername(),
+                sandboxName: sandboxProcessObj.SandboxName,
+                sandboxProcessId: sandboxProcessObj.Id,
+                sandboxInfoId: sandboxProcessObj.SandboxInfoId,
+                timestamp: new Date().toISOString(),
+            };
+            await this.setSandboxConfig(sandboxOrgId, sfSandbox);
+            await (await stateAggregator_1.StateAggregator.getInstance()).sandboxes.write(sandboxOrgId);
             await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_RESULT, {
                 sandboxProcessObj,
                 sandboxRes,
@@ -822,96 +1064,67 @@ class Org extends kit_1.AsyncOptionalCreatable {
             throw messages.createError('missingAuthUsername', [sandboxProcessObj.SandboxName]);
         }
     }
-    /**
-     * Polls for the new sandbox to be created - and will write the associated auth files
-     *
-     * @private
-     * @param options
-     *  sandboxProcessObj: The in-progress sandbox signup request
-     *  retries: the number of retries to poll for every 30s
-     *  shouldPoll: wait for polling, or just return
-     *  pollInterval: Duration to sleep between poll events, default 30 seconds
-     */
     async pollStatusAndAuth(options) {
-        var _a;
-        const { sandboxProcessObj, retries, shouldPoll, pollInterval } = options;
-        this.logger.debug('PollStatusAndAuth called with SandboxProcessObject%s, retries %s', sandboxProcessObj, retries);
-        const lifecycle = lifecycleEvents_1.Lifecycle.getInstance();
-        let pollFinished = false;
+        this.logger.debug('PollStatusAndAuth called with SandboxProcessObject', options.sandboxProcessObj, options.wait.minutes, options.pollInterval.seconds);
+        let remainingWait = options.wait;
         let waitingOnAuth = false;
-        const sandboxInfo = await this.sandboxSignupComplete(sandboxProcessObj);
-        if (sandboxInfo) {
-            await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_AUTH, sandboxInfo);
-            try {
-                this.logger.debug('sandbox signup complete with %s', sandboxInfo);
-                await this.writeSandboxAuthFile(sandboxProcessObj, sandboxInfo);
-                pollFinished = true;
-            }
-            catch (err) {
-                const error = err;
-                this.logger.debug('Exception while calling writeSandboxAuthFile %s', err);
-                if ((error === null || error === void 0 ? void 0 : error.name) === 'JWTAuthError' && ((_a = error === null || error === void 0 ? void 0 : error.stack) === null || _a === void 0 ? void 0 : _a.includes("user hasn't approved"))) {
-                    waitingOnAuth = true;
+        const pollingClient = await pollingClient_1.PollingClient.create({
+            poll: async () => {
+                const sandboxProcessObj = await this.querySandboxProcessBySandboxInfoId(options.sandboxProcessObj.SandboxInfoId);
+                // check to see if sandbox can authenticate via sandboxAuth endpoint
+                const sandboxInfo = await this.sandboxSignupComplete(sandboxProcessObj);
+                if (sandboxInfo) {
+                    await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_AUTH, sandboxInfo);
+                    try {
+                        this.logger.debug('sandbox signup complete with', sandboxInfo);
+                        await this.writeSandboxAuthFile(sandboxProcessObj, sandboxInfo);
+                        return { completed: true, payload: sandboxProcessObj };
+                    }
+                    catch (err) {
+                        const error = err;
+                        this.logger.debug('Exception while calling writeSandboxAuthFile', err);
+                        if (error?.name === 'JwtAuthError' && error?.stack?.includes("user hasn't approved")) {
+                            waitingOnAuth = true;
+                        }
+                        else {
+                            throw sfError_1.SfError.wrap(error);
+                        }
+                    }
                 }
-                else {
-                    throw sfdxError_1.SfdxError.wrap(error);
-                }
-            }
-        }
-        if (!pollFinished) {
-            if (retries > 0) {
-                // emit the signup progress of the sandbox and query the production org again after waiting the interval
-                await Promise.all([
-                    await lifecycle.emit(SandboxEvents.EVENT_STATUS, {
-                        sandboxProcessObj,
-                        interval: pollInterval.seconds,
-                        retries,
-                        waitingOnAuth,
-                    }),
-                    await (0, kit_1.sleep)(pollInterval),
-                ]);
-                const polledSandboxProcessObj = await this.querySandboxProcess(sandboxProcessObj.SandboxInfoId);
-                return this.pollStatusAndAuth({
-                    sandboxProcessObj: polledSandboxProcessObj,
-                    retries: retries - 1,
-                    shouldPoll,
-                    pollInterval,
+                await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_STATUS, {
+                    sandboxProcessObj,
+                    remainingWait: remainingWait.seconds,
+                    interval: options.pollInterval.seconds,
+                    waitingOnAuth,
                 });
-            }
-            else {
-                if (shouldPoll) {
-                    // timed out on retries
-                    throw messages.createError('orgPollingTimeout', [sandboxProcessObj.Status]);
-                }
-                else {
-                    // The user didn't want us to poll, so simply return the status
-                    // simply report status and exit
-                    await lifecycle.emit(SandboxEvents.EVENT_ASYNC_RESULT, sandboxProcessObj);
-                }
-            }
-        }
-        return sandboxProcessObj;
+                remainingWait = kit_1.Duration.seconds(remainingWait.seconds - options.pollInterval.seconds);
+                return { completed: false, payload: sandboxProcessObj };
+            },
+            frequency: options.pollInterval,
+            timeout: options.wait,
+        });
+        return pollingClient.subscribe();
     }
     /**
-     * query SandboxProcess via SandboxInfoId
+     * query SandboxProcess using supplied where clause
      *
-     * @param id SandboxInfoId to query for
+     * @param where clause to query for
      * @private
      */
-    async querySandboxProcess(id) {
-        const queryStr = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE SandboxInfoId='${id}' AND Status != 'D'`;
-        return await this.connection.singleRecordQuery(queryStr, {
+    async querySandboxProcess(where) {
+        const queryStr = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE ${where} AND Status != 'D'`;
+        return this.connection.singleRecordQuery(queryStr, {
             tooling: true,
         });
     }
     /**
      * determines if the sandbox has successfully been created
      *
-     * @param sandboxProcessObj sandbox signup progeress
+     * @param sandboxProcessObj sandbox signup progress
      * @private
      */
     async sandboxSignupComplete(sandboxProcessObj) {
-        this.logger.debug('sandboxSignupComplete called with SandboxProcessObject %s', sandboxProcessObj);
+        this.logger.debug('sandboxSignupComplete called with SandboxProcessObject', sandboxProcessObj);
         if (!sandboxProcessObj.EndDate) {
             return;
         }
@@ -925,7 +1138,8 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 sandboxName: sandboxProcessObj.SandboxName,
                 callbackUrl,
             };
-            this.logger.debug('Calling sandboxAuth with SandboxUserAuthRequest %s', sandboxReq);
+            this.logger.debug('Calling sandboxAuth with SandboxUserAuthRequest', sandboxReq);
+            // eslint-disable-next-line no-underscore-dangle
             const url = `${this.connection.tooling._baseUrl()}/sandboxAuth`;
             const params = {
                 method: 'POST',
@@ -934,22 +1148,49 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 body: JSON.stringify(sandboxReq),
             };
             const result = await this.connection.tooling.request(params);
-            this.logger.debug('Result of calling sandboxAuth %s', result);
+            this.logger.debug('Result of calling sandboxAuth', result);
             return result;
         }
         catch (err) {
             const error = err;
             // There are cases where the endDate is set before the sandbox has actually completed.
             // In that case, the sandboxAuth call will throw a specific exception.
-            if ((error === null || error === void 0 ? void 0 : error.name) === 'INVALID_STATUS') {
-                this.logger.debug('Error while authenticating the user %s', error === null || error === void 0 ? void 0 : error.toString());
+            if (error?.name === 'INVALID_STATUS') {
+                this.logger.debug('Error while authenticating the user', error?.toString());
             }
             else {
                 // If it fails for any unexpected reason, just pass that through
-                throw sfdxError_1.SfdxError.wrap(error);
+                throw sfError_1.SfError.wrap(error);
             }
         }
     }
+    validateWaitOptions(options) {
+        const wait = options.wait ?? kit_1.Duration.minutes(30);
+        const interval = options.interval ?? kit_1.Duration.seconds(30);
+        let pollInterval = options.async ? kit_1.Duration.seconds(0) : interval;
+        // pollInterval cannot be > wait.
+        pollInterval = pollInterval.seconds > wait.seconds ? wait : pollInterval;
+        return [wait, pollInterval];
+    }
+    /**
+     * removes source tracking files hosted in the project/.sf/orgs/<org id>/
+     *
+     * @private
+     */
+    async removeSourceTrackingFiles() {
+        try {
+            const rootFolder = await config_1.Config.resolveRootFolder(false);
+            await fs.promises.rm((0, path_1.join)(rootFolder, global_1.Global.SF_STATE_FOLDER, 'orgs', this.getOrgId()), {
+                recursive: true,
+                force: true,
+            });
+        }
+        catch (e) {
+            const err = sfError_1.SfError.wrap(e);
+            // consume the error in case something  went wrong
+            this.logger.debug(`error deleting source tracking information for ${this.getOrgId()} error: ${err.message}`);
+        }
+    }
 }
 exports.Org = Org;
 (function (Org) {
@@ -1033,6 +1274,11 @@ exports.Org = Org;
          * The snapshot used to create the scratch org.
          */
         Fields["SNAPSHOT"] = "snapshot";
+        /**
+         * true: the org supports and wants source tracking
+         * false: the org opted out of tracking or can't support it
+         */
+        Fields["TRACKS_SOURCE"] = "tracksSource";
         // Should it be on org? Leave it off for now, as it might
         // be confusing to the consumer what this actually is.
         // USERNAMES = 'usernames',