W-16441894 feat: @oclif/multi-stage-output

package.json

@@ -6,14 +6,16 @@
   "bugs": "https://github.com/forcedotcom/cli/issues",
   "dependencies": {
     "@oclif/core": "^4.0.16",
+    "@oclif/multi-stage-output": "^0.3.0",
     "@salesforce/core": "^8.4.0",
     "@salesforce/kit": "^3.2.0",
     "@salesforce/sf-plugins-core": "^11.3.3",
     "@salesforce/source-deploy-retrieve": "^12.1.12",
     "ansis": "^3.2.0",
     "change-case": "^5.4.4",
     "is-wsl": "^3.1.0",
-    "open": "^10.1.0"
+    "open": "^10.1.0",
+    "terminal-link": "^3.0.0"
   },
   "devDependencies": {
     "@oclif/plugin-command-snapshot": "^5.2.12",

src/commands/org/create/scratch.ts

@@ -5,25 +5,28 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
+import { MultiStageOutput } from '@oclif/multi-stage-output';
 import {
   Lifecycle,
   Messages,
   Org,
   scratchOrgCreate,
   ScratchOrgLifecycleEvent,
   scratchOrgLifecycleEventName,
+  scratchOrgLifecycleStages,
   SfError,
 } from '@salesforce/core';
 import { Flags, SfCommand } from '@salesforce/sf-plugins-core';
 import { Duration } from '@salesforce/kit';
+import terminalLink from 'terminal-link';
 import { buildScratchOrgRequest } from '../../../shared/scratchOrgRequest.js';
-import { buildStatus } from '../../../shared/scratchOrgOutput.js';
 import { ScratchCreateResponse } from '../../../shared/orgTypes.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-org', 'create_scratch');
 
 const definitionFileHelpGroupName = 'Definition File Override';
+
 export default class OrgCreateScratch extends SfCommand<ScratchCreateResponse> {
   public static readonly summary = messages.getMessage('summary');
   public static readonly description = messages.getMessage('description');
@@ -167,38 +170,69 @@ export default class OrgCreateScratch extends SfCommand<ScratchCreateResponse> {
       flags,
       flags['client-id'] ? await this.secretPrompt({ message: messages.getMessage('prompt.secret') }) : undefined
     );
-    let lastStatus: string | undefined;
 
-    if (!flags.async) {
-      lifecycle.on<ScratchOrgLifecycleEvent>(scratchOrgLifecycleEventName, async (data): Promise<void> => {
-        lastStatus = buildStatus(data, baseUrl);
-        this.spinner.status = lastStatus;
-        return Promise.resolve();
-      });
-    }
-    this.log();
-    this.spinner.start(
-      flags.async ? 'Requesting Scratch Org (will not wait for completion because --async)' : 'Creating Scratch Org'
-    );
+    const stager = new MultiStageOutput<ScratchOrgLifecycleEvent & { alias: string | undefined }>({
+      stages: flags.async ? ['prepare request', 'send request', 'done'] : scratchOrgLifecycleStages,
+      title: flags.async ? 'Creating Scratch Org (async)' : 'Creating Scratch Org',
+      data: { alias: flags.alias },
+      jsonEnabled: this.jsonEnabled(),
+      postStagesBlock: [
+        {
+          label: 'Request Id',
+          type: 'dynamic-key-value',
+          get: (data) =>
+            data?.scratchOrgInfo?.Id && terminalLink(data.scratchOrgInfo.Id, `${baseUrl}/${data.scratchOrgInfo.Id}`),
+          bold: true,
+        },
+        {
+          label: 'OrgId',
+          type: 'dynamic-key-value',
+          get: (data) => data?.scratchOrgInfo?.ScratchOrg,
+          bold: true,
+          color: 'cyan',
+        },
+        {
+          label: 'Username',
+          type: 'dynamic-key-value',
+          get: (data) => data?.scratchOrgInfo?.SignupUsername,
+          bold: true,
+          color: 'cyan',
+        },
+        {
+          label: 'Alias',
+          type: 'static-key-value',
+          get: (data) => data?.alias,
+        },
+      ],
+    });
+
+    lifecycle.on<ScratchOrgLifecycleEvent>(scratchOrgLifecycleEventName, async (data): Promise<void> => {
+      stager.goto(data.stage, data);
+      if (data.stage === 'done') {
+        stager.stop();
+      }
+      return Promise.resolve();
+    });
 
     try {
       const { username, scratchOrgInfo, authFields, warnings } = await scratchOrgCreate(createCommandOptions);
 
-      this.spinner.stop(lastStatus);
       if (!scratchOrgInfo) {
         throw new SfError('The scratch org did not return with any information');
       }
-      this.log();
+
       if (flags.async) {
+        stager.goto('done', { scratchOrgInfo });
+        stager.stop();
         this.info(messages.getMessage('action.resume', [this.config.bin, scratchOrgInfo.Id]));
       } else {
         this.logSuccess(messages.getMessage('success'));
       }
 
       return { username, scratchOrgInfo, authFields, warnings, orgId: authFields?.orgId };
     } catch (error) {
+      stager.stop(error as Error);
       if (error instanceof SfError && error.name === 'ScratchOrgInfoTimeoutError') {
-        this.spinner.stop(lastStatus);
         const scratchOrgInfoId = (error.data as { scratchOrgInfoId: string }).scratchOrgInfoId;
         const resumeMessage = messages.getMessage('action.resume', [this.config.bin, scratchOrgInfoId]);
 

src/commands/org/delete/sandbox.ts

@@ -15,7 +15,7 @@ const messages = Messages.loadMessages('@salesforce/plugin-org', 'delete_sandbox
 export type SandboxDeleteResponse = {
   orgId: string;
   username: string;
-}
+};
 
 export default class DeleteSandbox extends SfCommand<SandboxDeleteResponse> {
   public static readonly summary = messages.getMessage('summary');

src/commands/org/delete/scratch.ts

@@ -15,7 +15,7 @@ const messages = Messages.loadMessages('@salesforce/plugin-org', 'delete_scratch
 export type ScratchDeleteResponse = {
   orgId: string;
   username: string;
-}
+};
 
 export default class DeleteScratch extends SfCommand<ScratchDeleteResponse> {
   public static readonly summary = messages.getMessage('summary');

src/commands/org/resume/scratch.ts

@@ -14,11 +14,13 @@ import {
   ScratchOrgCache,
   ScratchOrgLifecycleEvent,
   scratchOrgLifecycleEventName,
+  scratchOrgLifecycleStages,
   scratchOrgResume,
   SfError,
 } from '@salesforce/core';
+import terminalLink from 'terminal-link';
+import { MultiStageOutput } from '@oclif/multi-stage-output';
 import { ScratchCreateResponse } from '../../../shared/orgTypes.js';
-import { buildStatus } from '../../../shared/scratchOrgOutput.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-org', 'resume_scratch');
@@ -55,26 +57,60 @@ export default class OrgResumeScratch extends SfCommand<ScratchCreateResponse> {
 
     // oclif doesn't know that the exactlyOne flag will ensure that one of these is set, and there we definitely have a jobID.
     assert(jobId);
-    const hubBaseUrl = cache.get(jobId)?.hubBaseUrl;
-    let lastStatus: string | undefined;
+    const cached = cache.get(jobId);
+    const hubBaseUrl = cached?.hubBaseUrl;
+
+    const stager = new MultiStageOutput<ScratchOrgLifecycleEvent & { alias: string | undefined }>({
+      stages: scratchOrgLifecycleStages,
+      title: 'Resuming Scratch Org',
+      data: { alias: cached?.alias },
+      jsonEnabled: this.jsonEnabled(),
+      postStagesBlock: [
+        {
+          label: 'Request Id',
+          type: 'dynamic-key-value',
+          get: (data) =>
+            data?.scratchOrgInfo?.Id && terminalLink(data.scratchOrgInfo.Id, `${hubBaseUrl}/${data.scratchOrgInfo.Id}`),
+          bold: true,
+        },
+        {
+          label: 'OrgId',
+          type: 'dynamic-key-value',
+          get: (data) => data?.scratchOrgInfo?.ScratchOrg,
+          bold: true,
+          color: 'cyan',
+        },
+        {
+          label: 'Username',
+          type: 'dynamic-key-value',
+          get: (data) => data?.scratchOrgInfo?.SignupUsername,
+          bold: true,
+          color: 'cyan',
+        },
+        {
+          label: 'Alias',
+          type: 'static-key-value',
+          get: (data) => data?.alias,
+        },
+      ],
+    });
 
     lifecycle.on<ScratchOrgLifecycleEvent>(scratchOrgLifecycleEventName, async (data): Promise<void> => {
-      lastStatus = buildStatus(data, hubBaseUrl);
-      this.spinner.status = lastStatus;
+      stager.goto(data.stage, data);
+      if (data.stage === 'done') {
+        stager.stop();
+      }
       return Promise.resolve();
     });
 
-    this.log();
-    this.spinner.start('Creating Scratch Org');
-
     try {
       const { username, scratchOrgInfo, authFields, warnings } = await scratchOrgResume(jobId);
-      this.spinner.stop(lastStatus);
-
       this.log();
       this.logSuccess(messages.getMessage('success'));
       return { username, scratchOrgInfo, authFields, warnings, orgId: authFields?.orgId };
     } catch (e) {
+      stager.stop(e as Error);
+
       if (cache.keys() && e instanceof Error && e.name === 'CacheMissError') {
         // we have something in the cache, but it didn't match what the user passed in
         throw messages.createError('error.jobIdMismatch', [jobId]);

src/shared/orgHooks.ts

@@ -34,7 +34,7 @@ type PostOrgCreateOpts = HookOpts<OrgCreateResult>;
  */
 export type OrgHooks = {
   postorgcreate: PostOrgCreateOpts;
-} & Interfaces.Hooks
+} & Interfaces.Hooks;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type OrgHook<T> = (this: Hook.Context, options: T extends keyof Interfaces.Hooks ? OrgHooks[T] : T) => any;

test/shared/scratchOrgRequest.test.ts

@@ -8,17 +8,17 @@ import { Config, Interfaces } from '@oclif/core';
 import { expect } from 'chai';
 import { MockTestOrgData, TestContext } from '@salesforce/core/testSetup';
 import { buildScratchOrgRequest } from '../../src/shared/scratchOrgRequest.js';
-import EnvCreateScratch from '../../src/commands/org/create/scratch.js';
+import OrgCreateScratch from '../../src/commands/org/create/scratch.js';
 
-class Wrapper extends EnvCreateScratch {
+class Wrapper extends OrgCreateScratch {
   // simple method to return the parsed flags so they can be used in the tests
   public async getFlags(): Promise<Interfaces.InferredFlags<typeof Wrapper.flags>> {
     return (await this.parse(Wrapper)).flags;
   }
 }
 
 /** pass in the params in array form, get back the parsed flags */
-const paramsToFlags = async (params: string[]): Promise<Interfaces.InferredFlags<typeof EnvCreateScratch.flags>> =>
+const paramsToFlags = async (params: string[]): Promise<Interfaces.InferredFlags<typeof OrgCreateScratch.flags>> =>
   new Wrapper(params, { runHook: () => ({ successes: [], failures: [] }) } as unknown as Config).getFlags();
 
 describe('buildScratchOrgRequest function', () => {

test/unit/org/resumeScratch.test.ts

@@ -34,7 +34,7 @@ describe('org:resume:scratch', () => {
     });
 
     try {
-      await OrgResumeScratch.run(['--job-id', '2SRFOOFOOFOOFOOFOO']);
+      await OrgResumeScratch.run(['--job-id', '2SRFOOFOOFOOFOOFOO', '--json']);
       expect(false, 'ResumeSandbox should have thrown sandboxCreateNotComplete');
     } catch (err: unknown) {
       const error = err as SfError;
@@ -50,7 +50,7 @@ describe('org:resume:scratch', () => {
     });
 
     try {
-      await OrgResumeScratch.run(['--job-id', '2SRFOOFOOFOOFOOFOO']);
+      await OrgResumeScratch.run(['--job-id', '2SRFOOFOOFOOFOOFOO', '--json']);
       expect(false, 'ResumeSandbox should have thrown sandboxCreateNotComplete');
     } catch (err: unknown) {
       const error = err as SfError;