feat: add --wait flag to sandbox clone create (#249)

clavery · web-flow · commit e790dfa8d537 · 2026-03-11T13:47:47.000-04:00
* feat: add --wait flag to sandbox clone create and fix config.bin template

Add --wait, --poll-interval, and --timeout flags to `sandbox clone create`
to poll until the clone reaches COMPLETED or FAILED, matching `sandbox create`.

Fix the status hint message which was outputting raw `&lt;%= config.bin %&gt;`
instead of the resolved binary name.

* chore: change changeset to patch

* fix: resolve lint errors in SDK wait-for-clone
diff --git a/.changeset/clone-create-wait-flag.md b/.changeset/clone-create-wait-flag.md
@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Add `--wait` flag to `sandbox clone create` command to poll until the clone completes, matching the behavior of `sandbox create --wait`. Also fixes the status check hint to display the correct command name instead of a raw template string.
diff --git a/packages/b2c-cli/src/commands/sandbox/clone/create.ts b/packages/b2c-cli/src/commands/sandbox/clone/create.ts
@@ -5,7 +5,13 @@
  */
 import {Args, Flags, Errors} from '@oclif/core';
 import {OdsCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import {getApiErrorMessage} from '@salesforce/b2c-tooling-sdk';
+import {
+  getApiErrorMessage,
+  waitForClone,
+  ClonePollingTimeoutError,
+  ClonePollingError,
+  CloneFailedError,
+} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
 
 /**
@@ -30,6 +36,8 @@ export default class CloneCreate extends OdsCommand<typeof CloneCreate> {
     '<%= config.bin %> <%= command.id %> <sandboxId> --target-profile large',
     '<%= config.bin %> <%= command.id %> <sandboxId> --ttl 48',
     '<%= config.bin %> <%= command.id %> <sandboxId> --target-profile large --ttl 48 --emails dev@example.com,qa@example.com',
+    '<%= config.bin %> <%= command.id %> <sandboxId> --wait',
+    '<%= config.bin %> <%= command.id %> <sandboxId> --wait --poll-interval 15',
   ];
 
   static flags = {
@@ -49,11 +57,26 @@ export default class CloneCreate extends OdsCommand<typeof CloneCreate> {
       required: false,
       default: 24,
     }),
+    wait: Flags.boolean({
+      char: 'w',
+      description: 'Wait for the clone to complete before returning',
+      default: false,
+    }),
+    'poll-interval': Flags.integer({
+      description: 'Polling interval in seconds when using --wait',
+      default: 10,
+      dependsOn: ['wait'],
+    }),
+    timeout: Flags.integer({
+      description: 'Maximum time to wait in seconds when using --wait (0 for no timeout)',
+      default: 1800,
+      dependsOn: ['wait'],
+    }),
   };
 
   async run(): Promise<{cloneId?: string}> {
     const {sandboxId: rawSandboxId} = this.args;
-    const {'target-profile': targetProfile, emails, ttl} = this.flags;
+    const {'target-profile': targetProfile, emails, ttl, wait, 'poll-interval': pollInterval, timeout} = this.flags;
 
     // Validate TTL
     if (ttl > 0 && ttl < 24) {
@@ -103,19 +126,65 @@ export default class CloneCreate extends OdsCommand<typeof CloneCreate> {
 
     const cloneId = result.data.data?.cloneId;
 
-    if (this.jsonEnabled()) {
-      return {cloneId};
+    if (!this.jsonEnabled()) {
+      this.log(t('commands.clone.create.success', '✓ Sandbox clone creation started successfully'));
+      this.log(t('commands.clone.create.cloneId', 'Clone ID: {{cloneId}}', {cloneId}));
     }
 
-    this.log(t('commands.clone.create.success', '✓ Sandbox clone creation started successfully'));
-    this.log(t('commands.clone.create.cloneId', 'Clone ID: {{cloneId}}', {cloneId}));
-    this.log(
-      t(
-        'commands.clone.create.checkStatus',
-        '\nTo check the clone status, run:\n  <%= config.bin %> ods clone get {{sandboxId}} {{cloneId}}',
-        {sandboxId, cloneId},
-      ),
-    );
+    if (wait && cloneId) {
+      this.log(t('commands.clone.create.waiting', 'Waiting for clone to complete...'));
+
+      try {
+        await waitForClone(this.odsClient, {
+          sandboxId,
+          cloneId,
+          pollIntervalSeconds: pollInterval,
+          timeoutSeconds: timeout,
+          onPoll: ({elapsedSeconds, status, progressPercentage}) => {
+            const progress = progressPercentage === undefined ? '' : ` (${progressPercentage}%)`;
+            this.logger.info(
+              {sandboxId, cloneId, elapsed: elapsedSeconds, status},
+              `[${elapsedSeconds}s] Status: ${status}${progress}`,
+            );
+          },
+        });
+      } catch (error) {
+        if (error instanceof ClonePollingTimeoutError) {
+          this.error(
+            t('commands.clone.create.timeout', 'Timeout waiting for clone after {{seconds}} seconds', {
+              seconds: String(error.timeoutSeconds),
+            }),
+          );
+        }
+
+        if (error instanceof CloneFailedError) {
+          this.error(t('commands.clone.create.failed', 'Clone operation failed'));
+        }
+
+        if (error instanceof ClonePollingError) {
+          this.error(
+            t('commands.clone.create.pollError', 'Failed to fetch clone status: {{message}}', {
+              message: error.message,
+            }),
+          );
+        }
+
+        throw error;
+      }
+
+      if (!this.jsonEnabled()) {
+        this.log(t('commands.clone.create.completed', '✓ Clone completed successfully'));
+      }
+    } else if (!this.jsonEnabled()) {
+      const bin = this.config.bin;
+      this.log(
+        t(
+          'commands.clone.create.checkStatus',
+          '\nTo check the clone status, run:\n  {{bin}} sandbox clone get {{sandboxId}} {{cloneId}}',
+          {bin, sandboxId, cloneId},
+        ),
+      );
+    }
 
     return {cloneId};
   }
diff --git a/packages/b2c-cli/test/commands/sandbox/clone/create.test.ts b/packages/b2c-cli/test/commands/sandbox/clone/create.test.ts
@@ -13,6 +13,7 @@ import {runSilent} from '../../../helpers/test-setup.js';
 function stubCommandConfigAndLogger(command: any, sandboxApiHost = 'admin.dx.test.com'): void {
   Object.defineProperty(command, 'config', {
     value: {
+      bin: 'b2c',
       findConfigFile: () => ({
         read: () => ({'sandbox-api-host': sandboxApiHost}),
       }),
@@ -231,7 +232,7 @@ describe('sandbox clone create', () => {
     it('should display formatted output in non-JSON mode', async () => {
       const command = new CloneCreate(['test-sandbox-id'], {} as any);
       (command as any).args = {sandboxId: 'test-sandbox-id'};
-      (command as any).flags = {'target-profile': 'medium', ttl: 24};
+      (command as any).flags = {'target-profile': 'medium', ttl: 24, wait: false, 'poll-interval': 10, timeout: 1800};
       stubJsonEnabled(command, false);
       stubCommandConfigAndLogger(command);
       stubResolveSandboxId(command, async (id) => id);
@@ -256,6 +257,9 @@ describe('sandbox clone create', () => {
       expect(combinedLogs).to.include('Clone ID');
       expect(combinedLogs).to.include(mockCloneId);
       expect(combinedLogs).to.include('started successfully');
+      // Verify the config.bin template is resolved, not raw EJS
+      expect(combinedLogs).to.not.include('<%= config.bin %>');
+      expect(combinedLogs).to.include('b2c sandbox clone get');
     });
 
     it('should pass emails to API when provided', async () => {
@@ -313,6 +317,129 @@ describe('sandbox clone create', () => {
     });
   });
 
+  describe('wait functionality', () => {
+    it('should have wait flag', () => {
+      expect(CloneCreate.flags).to.have.property('wait');
+      expect(CloneCreate.flags.wait.default).to.be.false;
+    });
+
+    it('should have poll-interval flag that depends on wait', () => {
+      expect(CloneCreate.flags).to.have.property('poll-interval');
+      expect(CloneCreate.flags['poll-interval'].default).to.equal(10);
+      expect(CloneCreate.flags['poll-interval'].dependsOn).to.deep.equal(['wait']);
+    });
+
+    it('should have timeout flag that depends on wait', () => {
+      expect(CloneCreate.flags).to.have.property('timeout');
+      expect(CloneCreate.flags.timeout.default).to.equal(1800);
+      expect(CloneCreate.flags.timeout.dependsOn).to.deep.equal(['wait']);
+    });
+
+    it('should poll until clone completes when --wait is used', async () => {
+      const command = new CloneCreate(['test-sandbox-id'], {} as any);
+      (command as any).args = {sandboxId: 'test-sandbox-id'};
+      (command as any).flags = {ttl: 24, wait: true, 'poll-interval': 0, timeout: 5};
+      stubJsonEnabled(command, true);
+      stubCommandConfigAndLogger(command);
+      stubResolveSandboxId(command, async (id) => id);
+
+      const mockCloneId = 'aaaa-001-1642780893121';
+      let getCalls = 0;
+
+      Object.defineProperty(command, 'odsClient', {
+        value: {
+          POST: async () => ({
+            data: {data: {cloneId: mockCloneId}},
+            response: new Response(),
+          }),
+          async GET() {
+            getCalls++;
+            const status = getCalls >= 2 ? 'COMPLETED' : 'IN_PROGRESS';
+            return {
+              data: {data: {status, cloneId: mockCloneId, progressPercentage: getCalls >= 2 ? 100 : 50}},
+              response: new Response(),
+            };
+          },
+        },
+        configurable: true,
+      });
+
+      const result = await command.run();
+
+      expect(result.cloneId).to.equal(mockCloneId);
+      expect(getCalls).to.be.greaterThanOrEqual(2);
+    });
+
+    it('should error when clone fails during wait', async () => {
+      const command = new CloneCreate(['test-sandbox-id'], {} as any);
+      (command as any).args = {sandboxId: 'test-sandbox-id'};
+      (command as any).flags = {ttl: 24, wait: true, 'poll-interval': 0, timeout: 5};
+      stubJsonEnabled(command, true);
+      stubCommandConfigAndLogger(command);
+      makeCommandThrowOnError(command);
+      stubResolveSandboxId(command, async (id) => id);
+
+      Object.defineProperty(command, 'odsClient', {
+        value: {
+          POST: async () => ({
+            data: {data: {cloneId: 'test-clone-id'}},
+            response: new Response(),
+          }),
+          GET: async () => ({
+            data: {data: {status: 'FAILED', cloneId: 'test-clone-id'}},
+            response: new Response(),
+          }),
+        },
+        configurable: true,
+      });
+
+      try {
+        await command.run();
+        expect.fail('Should have thrown');
+      } catch (error: unknown) {
+        expect((error as Error).message).to.include('failed');
+      }
+    });
+
+    it('should timeout if clone never completes', async () => {
+      const command = new CloneCreate(['test-sandbox-id'], {} as any);
+      (command as any).args = {sandboxId: 'test-sandbox-id'};
+      (command as any).flags = {ttl: 24, wait: true, 'poll-interval': 0, timeout: 1};
+      stubJsonEnabled(command, true);
+      stubCommandConfigAndLogger(command);
+      makeCommandThrowOnError(command);
+      stubResolveSandboxId(command, async (id) => id);
+
+      const clock = sinon.useFakeTimers({now: 0});
+
+      Object.defineProperty(command, 'odsClient', {
+        value: {
+          POST: async () => ({
+            data: {data: {cloneId: 'test-clone-id'}},
+            response: new Response(),
+          }),
+          GET: async () => ({
+            data: {data: {status: 'IN_PROGRESS', cloneId: 'test-clone-id'}},
+            response: new Response(),
+          }),
+        },
+        configurable: true,
+      });
+
+      const promise = command.run();
+      await clock.tickAsync(2000);
+
+      try {
+        await promise;
+        expect.fail('Expected timeout');
+      } catch (error: any) {
+        expect(error.message).to.include('Timeout waiting for clone');
+      } finally {
+        clock.restore();
+      }
+    });
+  });
+
   describe('error handling', () => {
     it('should throw error when API call fails', async () => {
       const command = new CloneCreate(['test-sandbox-id'], {} as any);
diff --git a/packages/b2c-tooling-sdk/src/index.ts b/packages/b2c-tooling-sdk/src/index.ts
@@ -255,9 +255,14 @@ export {
   SandboxPollingTimeoutError,
   SandboxPollingError,
   SandboxTerminalStateError,
+  waitForClone,
+  ClonePollingTimeoutError,
+  ClonePollingError,
+  CloneFailedError,
 } from './operations/ods/index.js';
 
 export type {SandboxState, WaitForSandboxOptions, WaitForSandboxPollInfo} from './operations/ods/index.js';
+export type {CloneState, WaitForCloneOptions, WaitForClonePollInfo} from './operations/ods/index.js';
 
 // Operations - CIP
 export {
diff --git a/packages/b2c-tooling-sdk/src/operations/ods/index.ts b/packages/b2c-tooling-sdk/src/operations/ods/index.ts
@@ -25,3 +25,7 @@ export {
 } from './wait-for-sandbox.js';
 
 export type {SandboxState, WaitForSandboxOptions, WaitForSandboxPollInfo} from './wait-for-sandbox.js';
+
+export {waitForClone, ClonePollingTimeoutError, ClonePollingError, CloneFailedError} from './wait-for-clone.js';
+
+export type {CloneState, WaitForCloneOptions, WaitForClonePollInfo} from './wait-for-clone.js';
diff --git a/packages/b2c-tooling-sdk/src/operations/ods/wait-for-clone.ts b/packages/b2c-tooling-sdk/src/operations/ods/wait-for-clone.ts
diff --git a/packages/b2c-tooling-sdk/test/operations/ods/wait-for-clone.test.ts b/packages/b2c-tooling-sdk/test/operations/ods/wait-for-clone.test.ts
