feat: scratch org lifecycle events

Author: mshanemc

src/exported.ts

@@ -105,7 +105,11 @@ export { PermissionSetAssignment, PermissionSetAssignmentFields } from './org/pe
 export { ScratchOrgCreateOptions, ScratchOrgCreateResult, scratchOrgCreate } from './org/scratchOrgCreate';
 
 export { ScratchOrgInfo } from './org/scratchOrgTypes';
-export { ScratchOrgLifecycleEvent, scratchOrgLifecycleEventName } from './org/scratchOrgLifeCycleEvents';
+export {
+  ScratchOrgLifecycleEvent,
+  scratchOrgLifecycleEventName,
+  scratchOrgLifecycleStages,
+} from './org/scratchOrgLifeCycleEvents';
 
 // Utility sub-modules
 export * from './util/sfdc';

src/org/scratchOrgCreate.ts

@@ -109,7 +109,7 @@ export const scratchOrgCreate = async (options: ScratchOrgCreateOptions): Promis
   const logger = await Logger.child('scratchOrgCreate');
 
   logger.debug('scratchOrgCreate');
-  await emit({ stage: 'building request' });
+  await emit({ stage: 'prepare request' });
   const {
     hubOrg,
     connectedAppConsumerKey,
@@ -178,7 +178,7 @@ export const scratchOrgCreate = async (options: ScratchOrgCreateOptions): Promis
   logger.debug(`scratch org username ${username}`);
 
   const configAggregator = new ConfigAggregator();
-  await emit({ stage: 'deploying', scratchOrgInfo: scratchOrgInfoResult });
+  await emit({ stage: 'deploy settings', scratchOrgInfo: scratchOrgInfoResult });
 
   const authInfo = await deploySettingsAndResolveUrl(
     scratchOrgAuthInfo,
@@ -192,6 +192,7 @@ export const scratchOrgCreate = async (options: ScratchOrgCreateOptions): Promis
   logger.trace('Settings deployed to org');
   /** updating the revision num to zero during org:creation if source members are created during org:create.This only happens for some specific scratch org definition file.*/
   await updateRevisionCounterToZero(scratchOrg);
+  await emit({ stage: 'done', scratchOrgInfo: scratchOrgInfoResult });
 
   return {
     username,

src/org/scratchOrgInfoApi.ts

@@ -190,7 +190,7 @@ export const authorizeScratchOrg = async (options: {
   retry?: number;
 }): Promise<AuthInfo> => {
   const { scratchOrgInfoComplete, hubOrg, clientSecret, signupTargetLoginUrlConfig, retry: maxRetries } = options;
-  await emit({ stage: 'authing', scratchOrgInfo: scratchOrgInfoComplete });
+  await emit({ stage: 'authenticate', scratchOrgInfo: scratchOrgInfoComplete });
   const logger = await Logger.child('authorizeScratchOrg');
   logger.debug(`scratchOrgInfoComplete: ${JSON.stringify(scratchOrgInfoComplete, null, 4)}`);
 
@@ -287,8 +287,9 @@ export const requestScratchOrgCreation = async (
 
   await checkOrgDoesntExist(scratchOrgInfo); // throw if it does exist.
   try {
-    await emit({ stage: 'requested' });
-    return hubOrg.getConnection().sobject('ScratchOrgInfo').create(scratchOrgInfo);
+    await emit({ stage: 'send request' });
+    // return await will cause this catch block to run instead of the caller's catch block
+    return await hubOrg.getConnection().sobject('ScratchOrgInfo').create(scratchOrgInfo);
   } catch (error) {
     // this is a jsforce error which contains the property "fields" which regular error don't
     const jsForceError = error as JsForceError;
@@ -323,13 +324,13 @@ export const pollForScratchOrgInfo = async (
         logger.debug(`polling client result: ${JSON.stringify(resultInProgress, null, 4)}`);
         // Once it's "done" we can return it
         if (resultInProgress.Status === 'Active' || resultInProgress.Status === 'Error') {
-          await emit({ stage: 'ready', scratchOrgInfo: resultInProgress as unknown as ScratchOrgInfo });
+          await emit({ stage: 'available', scratchOrgInfo: resultInProgress as unknown as ScratchOrgInfo });
           return {
             completed: true,
             payload: resultInProgress as unknown as AnyJson,
           };
         }
-        await emit({ stage: 'pending', scratchOrgInfo: resultInProgress as unknown as ScratchOrgInfo });
+        await emit({ stage: 'wait for org', scratchOrgInfo: resultInProgress as unknown as ScratchOrgInfo });
 
         logger.debug(`Scratch org status is ${resultInProgress.Status}`);
         return {

src/org/scratchOrgLifecycleEvents.ts

@@ -10,9 +10,17 @@ import { ScratchOrgInfo } from './scratchOrgTypes';
 const emitter = Lifecycle.getInstance();
 
 export const scratchOrgLifecycleEventName = 'scratchOrgLifecycleEvent';
-
+export const scratchOrgLifecycleStages = [
+  'prepare request',
+  'send request',
+  'wait for org',
+  'available',
+  'authenticate',
+  'deploy settings',
+  'done',
+] as const;
 export interface ScratchOrgLifecycleEvent {
-  stage: 'building request' | 'requested' | 'pending' | 'ready' | 'authing' | 'deploying';
+  stage: typeof scratchOrgLifecycleStages[number];
   scratchOrgInfo?: ScratchOrgInfo;
 }
 

test/unit/org/scratchOrgInfoApiTest.ts

@@ -24,6 +24,7 @@ import {
 } from '../../../src/org/scratchOrgInfoApi';
 import { ScratchOrgInfo } from '../../../src/org/scratchOrgTypes';
 import { Messages } from '../../../src/messages';
+import { SfError } from '../../../src/sfError';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/core', 'scratchOrgInfoApi');
@@ -138,9 +139,12 @@ describe('requestScratchOrgCreation', () => {
     const err = new Error('MyError');
     err.name = 'NamedOrgNotFound';
     stubMethod(sandbox, AuthInfo, 'create').rejects(err);
-    const jsForceError = new Error('JsForce-Error') as JsForceError;
-    jsForceError.errorCode = 'REQUIRED_FIELD_MISSING';
-    jsForceError.fields = ['error-field'];
+    const jsForceError = {
+      ...new Error('JsForce-Error'),
+      errorCode: 'REQUIRED_FIELD_MISSING',
+      fields: ['error-field'],
+    } as JsForceError;
+
     // @ts-ignore
     connectionStub.sobject.withArgs('ScratchOrgInfo').returns({
       create: sinon.stub().rejects(jsForceError),
@@ -150,10 +154,10 @@ describe('requestScratchOrgCreation', () => {
     try {
       await shouldThrow(requestScratchOrgCreation(hubOrg, TEMPLATE_SCRATCH_ORG_INFO, settings));
     } catch (error) {
-      expect(error).to.exist;
-      expect(error.message).to.include(
-        messages.getMessage('SignupFieldsMissingError', [jsForceError.fields.toString()])
-      );
+      const e = error as SfError;
+      expect(e).to.exist;
+      expect(e).to.have.property('message');
+      expect(e.message).to.include(messages.getMessage('SignupFieldsMissingError', [jsForceError.fields.toString()]));
     }
   });