feat: lifecycle events for scratch org create

Author: mshanemc

src/exported.ts

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

src/org/scratchOrgCreate.ts

@@ -17,12 +17,13 @@ import {
   requestScratchOrgCreation,
   pollForScratchOrgInfo,
   deploySettingsAndResolveUrl,
-  ScratchOrgInfo,
 } from './scratchOrgInfoApi';
+import { ScratchOrgInfo } from './scratchOrgTypes';
 import SettingsGenerator from './scratchOrgSettingsGenerator';
 import { generateScratchOrgInfo, getScratchOrgInfoPayload } from './scratchOrgInfoGenerator';
 import { AuthFields, AuthInfo } from './authInfo';
 import { Connection } from './connection';
+import { emit } from './scratchOrgLifecycleEvents';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.load('@salesforce/core', 'scratchOrgCreate', [
@@ -106,8 +107,9 @@ const validateWait = (wait: Duration): void => {
 
 export const scratchOrgCreate = async (options: ScratchOrgCreateOptions): Promise<ScratchOrgCreateResult> => {
   const logger = await Logger.child('scratchOrgCreate');
-  logger.debug('scratchOrgCreate');
 
+  logger.debug('scratchOrgCreate');
+  await emit({ stage: 'building request' });
   const {
     hubOrg,
     connectedAppConsumerKey,
@@ -151,7 +153,6 @@ export const scratchOrgCreate = async (options: ScratchOrgCreateOptions): Promis
 
   // creates the scratch org info in the devhub
   const scratchOrgInfoRequestResult = await requestScratchOrgCreation(hubOrg, scratchOrgInfo, settingsGenerator);
-
   const scratchOrgInfoId = ensureString(getString(scratchOrgInfoRequestResult, 'id'));
 
   logger.debug(`scratch org has recordId ${scratchOrgInfoId}`);
@@ -177,6 +178,8 @@ export const scratchOrgCreate = async (options: ScratchOrgCreateOptions): Promis
   logger.debug(`scratch org username ${username}`);
 
   const configAggregator = new ConfigAggregator();
+  await emit({ stage: 'deploying', scratchOrgInfo: scratchOrgInfoResult });
+
   const authInfo = await deploySettingsAndResolveUrl(
     scratchOrgAuthInfo,
     apiversion ??

src/org/scratchOrgErrorCodes.ts

@@ -9,7 +9,7 @@ import { Optional } from '@salesforce/ts-types';
 import { Messages } from '../messages';
 import { SfError } from '../sfError';
 import { Logger } from '../logger';
-import { ScratchOrgInfo } from './scratchOrgInfoApi';
+import { ScratchOrgInfo } from './scratchOrgTypes';
 
 const WORKSPACE_CONFIG_FILENAME = 'sfdx-project.json';
 

src/org/scratchOrgInfoApi.ts

@@ -22,44 +22,9 @@ import { MyDomainResolver } from '../status/myDomainResolver';
 import { AuthInfo } from './authInfo';
 import { Org } from './org';
 import { checkScratchOrgInfoForErrors } from './scratchOrgErrorCodes';
-import SettingsGenerator, { ObjectSetting } from './scratchOrgSettingsGenerator';
-export interface ScratchOrgInfo {
-  AdminEmail?: string;
-  readonly CreatedDate?: string;
-  ConnectedAppCallbackUrl?: string;
-  ConnectedAppConsumerKey?: string;
-  Country?: string;
-  Description?: string;
-  DurationDays?: string;
-  Edition?: string;
-  readonly ErrorCode?: string;
-  readonly ExpirationDate?: string;
-  Features?: string;
-  HasSampleData?: boolean;
-  readonly Id?: string;
-  Language?: string;
-  LoginUrl: string;
-  readonly Name?: string;
-  Namespace?: string;
-  OrgName?: string;
-  Release?: 'Current' | 'Previous' | 'Preview';
-  readonly ScratchOrg?: string;
-  SourceOrg?: string;
-  readonly AuthCode: string;
-  Snapshot: string;
-  readonly Status: 'New' | 'Creating' | 'Active' | 'Error' | 'Deleted';
-  readonly SignupEmail: string;
-  readonly SignupUsername: string;
-  readonly SignupInstance: string;
-  Username: string;
-  settings?: Record<string, unknown>;
-  objectSettings?: { [objectName: string]: ObjectSetting };
-  orgPreferences?: {
-    enabled: string[];
-    disabled: string[];
-  };
-}
-
+import SettingsGenerator from './scratchOrgSettingsGenerator';
+import { ScratchOrgInfo } from './scratchOrgTypes';
+import { emit } from './scratchOrgLifecycleEvents';
 export interface JsForceError extends Error {
   errorCode: string;
   fields: string[];
@@ -225,6 +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 });
   const logger = await Logger.child('authorizeScratchOrg');
   logger.debug(`scratchOrgInfoComplete: ${JSON.stringify(scratchOrgInfoComplete, null, 4)}`);
 
@@ -321,7 +287,8 @@ export const requestScratchOrgCreation = async (
 
   await checkOrgDoesntExist(scratchOrgInfo); // throw if it does exist.
   try {
-    return await hubOrg.getConnection().sobject('ScratchOrgInfo').create(scratchOrgInfo);
+    await emit({ stage: 'requested' });
+    return 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;
@@ -356,11 +323,14 @@ 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 });
           return {
             completed: true,
             payload: resultInProgress as unknown as AnyJson,
           };
         }
+        await emit({ stage: 'pending', scratchOrgInfo: resultInProgress as unknown as ScratchOrgInfo });
+
         logger.debug(`Scratch org status is ${resultInProgress.Status}`);
         return {
           completed: false,

src/org/scratchOrgInfoGenerator.ts

@@ -13,7 +13,7 @@ import { WebOAuthServer } from '../webOAuthServer';
 import { Messages } from '../messages';
 import { SfError } from '../sfError';
 import { Org } from './org';
-import { ScratchOrgInfo } from './scratchOrgInfoApi';
+import { ScratchOrgInfo } from './scratchOrgTypes';
 import { ScratchOrgFeatureDeprecation } from './scratchOrgFeatureDeprecation';
 
 const defaultConnectedAppInfo = {

src/org/scratchOrgLifecycleEvents.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2020, salesforce.com, inc.
+ * All rights reserved.
+ * 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
+ */
+import { Lifecycle } from '../lifecycleEvents';
+import { ScratchOrgInfo } from './scratchOrgTypes';
+
+const emitter = Lifecycle.getInstance();
+
+export const scratchOrgLifecycleEventName = 'scratchOrgLifecycleEvent';
+
+export interface ScratchOrgLifecycleEvent {
+  stage: 'building request' | 'requested' | 'pending' | 'ready' | 'authing' | 'deploying';
+  scratchOrgInfo?: ScratchOrgInfo;
+}
+
+export const emit = async (event: ScratchOrgLifecycleEvent) => {
+  emitter.emit(scratchOrgLifecycleEventName, event);
+};

src/org/scratchOrgSettingsGenerator.ts

@@ -15,7 +15,7 @@ import { JsonAsXml } from '../util/jsonXmlTools';
 import { ZipWriter } from '../util/zipWriter';
 import { StatusResult } from '../status/types';
 import { PollingClient } from '../status/pollingClient';
-import { ScratchOrgInfo } from './scratchOrgInfoApi';
+import { ScratchOrgInfo, ObjectSetting } from './scratchOrgTypes';
 import { Org } from './org';
 
 export enum RequestStatus {
@@ -30,11 +30,6 @@ export enum RequestStatus {
 
 const breakPolling = ['Succeeded', 'SucceededPartial', 'Failed', 'Canceled'];
 
-export interface ObjectSetting extends JsonMap {
-  sharingModel?: string;
-  defaultRecordType?: string;
-}
-
 interface ObjectToBusinessProcessPicklist {
   [key: string]: {
     fullName: string;

src/org/scratchOrgTypes.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2020, salesforce.com, inc.
+ * All rights reserved.
+ * 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
+ */
+
+import { JsonMap } from '@salesforce/ts-types';
+
+export interface ScratchOrgInfo {
+  AdminEmail?: string;
+  readonly CreatedDate?: string;
+  ConnectedAppCallbackUrl?: string;
+  ConnectedAppConsumerKey?: string;
+  Country?: string;
+  Description?: string;
+  DurationDays?: string;
+  Edition?: string;
+  readonly ErrorCode?: string;
+  readonly ExpirationDate?: string;
+  Features?: string;
+  HasSampleData?: boolean;
+  readonly Id?: string;
+  Language?: string;
+  LoginUrl: string;
+  readonly Name?: string;
+  Namespace?: string;
+  OrgName?: string;
+  Release?: 'Current' | 'Previous' | 'Preview';
+  readonly ScratchOrg?: string;
+  SourceOrg?: string;
+  readonly AuthCode: string;
+  Snapshot: string;
+  readonly Status: 'New' | 'Creating' | 'Active' | 'Error' | 'Deleted';
+  readonly SignupEmail: string;
+  readonly SignupUsername: string;
+  readonly SignupInstance: string;
+  Username: string;
+  settings?: Record<string, unknown>;
+  objectSettings?: { [objectName: string]: ObjectSetting };
+  orgPreferences?: {
+    enabled: string[];
+    disabled: string[];
+  };
+}
+
+export interface ObjectSetting extends JsonMap {
+  sharingModel?: string;
+  defaultRecordType?: string;
+}

test/unit/org/scratchOrgErrorCodesTest.ts

@@ -8,7 +8,7 @@ import { expect } from 'chai';
 import { assert } from 'sinon';
 import { Logger } from '../../../src/logger';
 import { SfError } from '../../../src/sfError';
-import { ScratchOrgInfo } from '../../../src/org/scratchOrgInfoApi';
+import { ScratchOrgInfo } from '../../../src/org/scratchOrgTypes';
 import { checkScratchOrgInfoForErrors } from '../../../src/org/scratchOrgErrorCodes';
 
 const testUsername = 'foo';

test/unit/org/scratchOrgInfoApiTest.ts

@@ -17,12 +17,12 @@ import { MyDomainResolver } from '../../../src/status/myDomainResolver';
 import SettingsGenerator from '../../../src/org/scratchOrgSettingsGenerator';
 import {
   requestScratchOrgCreation,
-  ScratchOrgInfo,
   JsForceError,
   deploySettingsAndResolveUrl,
   pollForScratchOrgInfo,
   authorizeScratchOrg,
 } from '../../../src/org/scratchOrgInfoApi';
+import { ScratchOrgInfo } from '../../../src/org/scratchOrgTypes';
 import { Messages } from '../../../src/messages';
 
 Messages.importMessagesDirectory(__dirname);

test/unit/org/scratchOrgSettingsGeneratorTest.ts

@@ -11,7 +11,7 @@ import { assert, expect } from 'chai';
 import { Org, Connection } from '../../../src/org';
 import { sfdc } from '../../../src/util/sfdc';
 import { ZipWriter } from '../../../src/util/zipWriter';
-import { ScratchOrgInfo } from '../../../src/org/scratchOrgInfoApi';
+import { ScratchOrgInfo } from '../../../src/org/scratchOrgTypes';
 import SettingsGenerator from '../../../src/org/scratchOrgSettingsGenerator';
 import { MockTestOrgData } from '../../../src/testSetup';