feat: add source flags for sbx create (#1237)

* feat: name fields for definitionfile

* fix: update the changes

* fix: definition-file refresh payload

* testing

* feat: create flag and field for sandbox

* fix: update the name and id for definition file

* fix: sandbox name

* fix: update sourceSandboxName and Id

* fix: update the fields and error messages

* fix: update the error message

* fix: update the error messages

* fix: update the snapshot of alias clone

* fix: error message

* fix: update clone message

* fix: validate error messages for cloning

* chore: ci-rerun

* fix: add validation and messages

* fix: message description

---------

Co-authored-by: Cristian Dominguez <[email protected]>

Author: soridalac

command-snapshot.json

@@ -2,12 +2,11 @@
   {
     "alias": ["env:create:sandbox"],
     "command": "org:create:sandbox",
-    "flagAliases": [],
-    "flagChars": ["a", "c", "f", "i", "l", "n", "o", "s", "w"],
+    "flagAliases": ["c", "clone"],
+    "flagChars": ["a", "f", "i", "l", "n", "o", "s", "w"],
     "flags": [
       "alias",
       "async",
-      "clone",
       "definition-file",
       "flags-dir",
       "json",
@@ -17,6 +16,8 @@
       "no-track-source",
       "poll-interval",
       "set-default",
+      "source-id",
+      "source-sandbox-name",
       "target-org",
       "wait"
     ],

messages/clone.md

@@ -1,10 +1,10 @@
-# missingSourceSandboxName
+# missingSourceSandboxNameORSourceId
 
-Specify a value for %s in a definition file or on the command line.
+Specify a value for name or ID in a definition file or on the command line.
 
-# missingSourceSandboxNameAction
+# missingSourceSandboxNameORSourceIdAction
 
-To indicate which sandbox org you want to clone, specify %s in a definition file or as a command line argument.
+To indicate which sandbox org you want to clone, specify name or ID in a definition file or as a command line argument.
 
 # error.bothApexClassIdAndNameProvided
 
@@ -21,3 +21,19 @@ Unable to find the ID of the activation user group "%s" that's defined in the de
 # error.apexClassQueryFailed
 
 Unable to find the ID of the Apex class "%s" that's defined in the definition file.
+
+# error.bothSourceIdAndNameProvided
+
+You can't specify both `SourceId` and `SourceSandboxName` in the definition file at the same time.
+
+# error.sandboxNameQueryFailed
+
+Unable to find the ID of the sandbox "%s" that's defined in the definition file or as a command line argument.
+
+# error.bothSourceIdAndLicenseTypeProvided
+
+You can't specify both `SourceId` and `LicenseType` in the definition file at the same time.
+
+# error.bothSourceSandboxNameAndLicenseTypeProvided
+
+You can't specify both `SourceSandboxName` and `LicenseType` in the definition file at the same time.

messages/create.sandbox.md

@@ -6,7 +6,7 @@ Create a sandbox org.
 
 There are two ways to create a sandbox org: specify a definition file that contains the sandbox options or use the --name and --license-type flags to specify the two required options. If you want to set an option other than name or license type, such as apexClassId, you must use a definition file.
 
-You can also use this command to clone an existing sandbox. Use the --clone flag to specify the existing sandbox name and the --name flag to the name of the new sandbox.
+You can also use this command to clone an existing sandbox. Use the --source-sandbox-name flag to specify the existing sandbox name and the --name flag to the name of the new sandbox.
 
 # examples
 
@@ -20,7 +20,7 @@ You can also use this command to clone an existing sandbox. Use the --clone flag
 
 - Clone the existing sandbox with name "ExistingSandbox" and name the new sandbox "NewClonedSandbox". Set the new sandbox as your default org. Wait for 30 minutes for the sandbox creation to complete.
 
-  <%= config.bin %> <%= command.id %> --clone ExistingSandbox --name NewClonedSandbox --target-org prodOrg --alias MyDevSandbox --set-default --wait 30
+  <%= config.bin %> <%= command.id %> --source-sandbox-name ExistingSandbox --name NewClonedSandbox --target-org prodOrg --alias MyDevSandbox --set-default --wait 30
 
 # flags.setDefault.summary
 
@@ -58,13 +58,25 @@ Name of the sandbox org.
 
 The name must be a unique alphanumeric string (10 or fewer characters) to identify the sandbox. You can’t reuse a name while a sandbox is in the process of being deleted.
 
-# flags.clone.summary
+# flags.source-sandbox-name.summary
 
 Name of the sandbox org to clone.
 
-# flags.clone.description
+# flags.source-sandbox-name.description
 
-The value of --clone must be an existing sandbox. The existing sandbox, and the new sandbox specified with the --name flag, must both be associated with the production org (--target-org) that contains the sandbox licenses.
+The value of --source-sandbox-name must be an existing sandbox. The existing sandbox, and the new sandbox specified with the --name flag, must both be associated with the production org (--target-org) that contains the sandbox licenses.
+
+You can specify either --source-sandbox-name or --source-id when cloning an existing sandbox, but not both.
+
+# flags.source-id.summary
+
+ID of the sandbox org to clone.
+
+# flags.source-id.description
+
+The value of --source-id must be an existing sandbox. The existing sandbox, and the new sandbox specified with the --name flag, must both be associated with the production org (--target-org) that contains the sandbox licenses.
+
+You can specify either --source-sandbox-name or --source-id when cloning an existing sandbox, but not both.
 
 # flags.licenseType.summary
 
@@ -120,6 +132,14 @@ The sandbox request configuration isn't acceptable.
 
 The poll interval (%d seconds) can't be larger that wait (%d in seconds)
 
-# error.noCloneSource
+# error.bothIdFlagAndDefFilePropertyAreProvided
+
+You can't specify both the --source-id and --definition-file flags, and also include the "SourceId" option in the definition file. Pick one method of cloning a sandbox and try again.
+
+# error.bothNameFlagAndDefFilePropertyAreProvided
+
+You can't specify both the --source-sandbox-name and --definition-file flags, and also include the "SourceSandboxName" option in the definition file. Pick one method of cloning a sandbox and try again.
+
+# error.bothIdFlagAndNameDefFileAreNotAllowed
 
-Could not find the clone sandbox name "%s" in the target org.
+You can't specify both the --source-sandbox-name and --definition-file flags, and also include the "SourceId" option in the definition file. Same with the --source-id flag and "SourceSandboxName" option. Pick one method of cloning a sandbox and try again.

src/commands/org/create/sandbox.ts

@@ -9,7 +9,7 @@ import { Duration } from '@salesforce/kit';
 import { Flags } from '@salesforce/sf-plugins-core';
 import { Lifecycle, Messages, SandboxEvents, SandboxRequest, SfError } from '@salesforce/core';
 import { Interfaces } from '@oclif/core';
-import requestFunctions from '../../../shared/sandboxRequest.js';
+import requestFunctions, { readSandboxDefFile } from '../../../shared/sandboxRequest.js';
 import { SandboxCommandBase, SandboxCommandResponse } from '../../../shared/sandboxCommandBase.js';
 import { SandboxLicenseType } from '../../../shared/orgTypes.js';
 
@@ -27,6 +27,7 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxCommandResp
   public static readonly aliases = ['env:create:sandbox'];
   public static readonly deprecateAliases = true;
 
+  // eslint-disable-next-line sf-plugin/spread-base-flags
   public static flags = {
     // needs to change when new flags are available
     'definition-file': Flags.file({
@@ -79,18 +80,26 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxCommandResp
         return Promise.resolve(name);
       },
     }),
-    clone: Flags.string({
-      char: 'c',
-      summary: messages.getMessage('flags.clone.summary'),
-      description: messages.getMessage('flags.clone.description'),
+    'source-sandbox-name': Flags.string({
+      summary: messages.getMessage('flags.source-sandbox-name.summary'),
+      description: messages.getMessage('flags.source-sandbox-name.description'),
+      exclusive: ['license-type', 'source-id'],
+      deprecateAliases: true,
+      aliases: ['clone', 'c'],
+    }),
+    'source-id': Flags.salesforceId({
+      summary: messages.getMessage('flags.source-id.summary'),
+      description: messages.getMessage('flags.source-id.description'),
       exclusive: ['license-type'],
+      length: 'both',
+      char: undefined,
     }),
     'license-type': Flags.custom<SandboxLicenseType>({
       options: getLicenseTypes(),
     })({
       char: 'l',
       summary: messages.getMessage('flags.licenseType.summary'),
-      exclusive: ['clone'],
+      exclusive: ['source-sandbox-name', 'source-id'],
     }),
     'target-org': Flags.requiredOrg({
       char: 'o',
@@ -112,6 +121,7 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxCommandResp
   public async run(): Promise<SandboxCommandResponse> {
     this.sandboxRequestConfig = await this.getSandboxRequestConfig();
     this.flags = (await this.parse(CreateSandbox)).flags;
+
     this.debug('Create started with args %s ', this.flags);
     this.validateFlags();
     return this.createSandbox();
@@ -129,17 +139,25 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxCommandResp
     // reuse the existing sandbox request generator, with this command's flags as the varargs
     const requestOptions = {
       ...(this.flags.name ? { SandboxName: this.flags.name } : {}),
-      ...(this.flags.clone ? { SourceSandboxName: this.flags.clone } : {}),
-      ...(!this.flags.clone && this.flags['license-type'] ? { LicenseType: this.flags['license-type'] } : {}),
+      ...(this.flags['source-sandbox-name']
+        ? { SourceSandboxName: this.flags['source-sandbox-name'] }
+        : this.flags['source-id']
+        ? { SourceId: this.flags['source-id'] }
+        : {}),
+      ...(!this.flags['source-sandbox-name'] && !this.flags['source-id'] && this.flags['license-type']
+        ? { LicenseType: this.flags['license-type'] }
+        : {}),
     };
-    const { sandboxReq } = !this.flags.clone
-      ? await requestFunctions.createSandboxRequest(false, this.flags['definition-file'], undefined, requestOptions)
-      : await requestFunctions.createSandboxRequest(true, this.flags['definition-file'], undefined, requestOptions);
+
+    const { sandboxReq, srcSandboxName, srcId } = await requestFunctions.createSandboxRequest(
+      this.flags['definition-file'],
+      undefined,
+      requestOptions
+    );
 
     let apexId: string | undefined;
     let groupId: string | undefined;
 
-    // Determine which value to use
     if (sandboxReq.ApexClassName) {
       apexId = await requestFunctions.getApexClassIdByName(
         this.flags['target-org'].getConnection(),
@@ -155,9 +173,13 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxCommandResp
       );
       delete sandboxReq.ActivationUserGroupName;
     }
+
     return {
       ...sandboxReq,
-      ...(this.flags.clone ? { SourceId: await this.getSourceId() } : {}),
+      ...(srcSandboxName
+        ? { SourceId: await requestFunctions.getSrcIdByName(this.flags['target-org'].getConnection(), srcSandboxName) }
+        : {}),
+      ...(srcId ? { SourceId: srcId } : {}),
       ...(apexId ? { ApexClassId: apexId } : {}),
       ...(groupId ? { ActivationUserGroupId: groupId } : {}),
     };
@@ -176,7 +198,9 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxCommandResp
       tracksSource: this.flags['no-track-source'] === true ? false : undefined,
     });
     const sandboxReq = await this.createSandboxRequest();
-    await this.confirmSandboxReq({ ...sandboxReq, ...(this.flags.clone ? { CloneSource: this.flags.clone } : {}) });
+    await this.confirmSandboxReq({
+      ...sandboxReq,
+    });
     this.initSandboxProcessData(sandboxReq);
 
     if (!this.flags.async) {
@@ -265,17 +289,21 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxCommandResp
         this.flags.wait.seconds,
       ]);
     }
-  }
-
-  private async getSourceId(): Promise<string | undefined> {
-    if (!this.flags.clone) {
+    if (!this.flags['definition-file']) {
       return undefined;
     }
-    try {
-      const sourceOrg = await this.flags['target-org'].querySandboxProcessBySandboxName(this.flags.clone);
-      return sourceOrg.SandboxInfoId;
-    } catch (err) {
-      throw messages.createError('error.noCloneSource', [this.flags.clone], [], err as Error);
+    const parsedDef = readSandboxDefFile(this.flags['definition-file']);
+    if (this.flags['source-id'] && parsedDef.SourceId) {
+      throw messages.createError('error.bothIdFlagAndDefFilePropertyAreProvided');
+    }
+    if (this.flags['source-sandbox-name'] && parsedDef.SourceSandboxName) {
+      throw messages.createError('error.bothNameFlagAndDefFilePropertyAreProvided');
+    }
+    if (this.flags['source-id'] && parsedDef.SourceSandboxName) {
+      throw messages.createError('error.bothIdFlagAndNameDefFileAreNotAllowed');
+    }
+    if (this.flags['source-sandbox-name'] && parsedDef.SourceId) {
+      throw messages.createError('error.bothIdFlagAndNameDefFileAreNotAllowed');
     }
   }
 }

src/shared/sandboxRequest.ts

@@ -24,7 +24,7 @@ export const generateSboxName = async (): Promise<string> => {
 // Reads the sandbox definition file and converts properties to CapCase.
 export function readSandboxDefFile(
   defFile: string
-): Partial<SandboxInfo & { ApexClassName?: string; ActivationUserGroupName?: string }> {
+): Partial<SandboxInfo & { ApexClassName?: string; ActivationUserGroupName?: string; SourceSandboxName?: string }> {
   const fileContent = fs.readFileSync(defFile, 'utf-8');
   const parsedContent = lowerToUpper(JSON.parse(fileContent) as Record<string, unknown>);
 
@@ -36,11 +36,23 @@ export function readSandboxDefFile(
   if (parsedContent.ActivationUserGroupId && parsedContent.ActivationUserGroupName) {
     throw cloneMessages.createError('error.bothUserGroupIdAndNameProvided');
   }
+
+  if (parsedContent.SourceId && parsedContent.SourceSandboxName) {
+    throw cloneMessages.createError('error.bothSourceIdAndNameProvided');
+  }
+
+  if (parsedContent.SourceId && parsedContent.LicenseType) {
+    throw cloneMessages.createError('error.bothSourceIdAndLicenseTypeProvided');
+  }
+
+  if (parsedContent.LicenseType && parsedContent.SourceSandboxName) {
+    throw cloneMessages.createError('error.bothSourceSandboxNameAndLicenseTypeProvided');
+  }
+
   return parsedContent as Partial<SandboxInfo>;
 }
 
 export async function createSandboxRequest(
-  isClone: true,
   definitionFile: string | undefined,
   logger?: Logger | undefined,
   properties?: Record<string, string | undefined>
@@ -50,9 +62,9 @@ export async function createSandboxRequest(
     ActivationUserGroupName: string | undefined;
   };
   srcSandboxName: string;
+  srcId: string;
 }>;
 export async function createSandboxRequest(
-  isClone: false,
   definitionFile: string | undefined,
   logger?: Logger | undefined,
   properties?: Record<string, string | undefined>
@@ -63,11 +75,10 @@ export async function createSandboxRequest(
   };
 }>;
 export async function createSandboxRequest(
-  isClone = false,
   definitionFile: string | undefined,
   logger?: Logger | undefined,
   properties?: Record<string, string | undefined>
-): Promise<{ sandboxReq: SandboxRequest; srcSandboxName?: string }> {
+): Promise<{ sandboxReq: SandboxRequest; srcSandboxName?: string; srcId?: string }> {
   if (!logger) {
     logger = await Logger.child('createSandboxRequest');
   }
@@ -76,29 +87,28 @@ export async function createSandboxRequest(
   const sandboxDefFileContents = definitionFile ? readSandboxDefFile(definitionFile) : {};
 
   const capitalizedVarArgs = properties ? lowerToUpper(properties) : {};
-
   // varargs override file input
-  const sandboxReqWithName: SandboxRequest & { SourceSandboxName?: string } = {
+  const sandboxReqWithName: SandboxRequest & { SourceSandboxName?: string; SourceId?: string } = {
     ...(sandboxDefFileContents as Record<string, unknown>),
     ...capitalizedVarArgs,
     SandboxName:
       (capitalizedVarArgs.SandboxName as string) ??
       (sandboxDefFileContents.SandboxName as string) ??
       (await generateSboxName()),
   };
-
-  const { SourceSandboxName, ...sandboxReq } = sandboxReqWithName;
+  const isClone = sandboxReqWithName.SourceSandboxName ?? sandboxReqWithName.SourceId;
+  const { SourceSandboxName, SourceId, ...sandboxReq } = sandboxReqWithName;
   logger.debug('SandboxRequest after merging DefFile and Varargs: %s ', sandboxReq);
 
   if (isClone) {
-    if (!SourceSandboxName) {
-      // error - we need SourceSandboxName to know which sandbox to clone from
+    if (!sandboxReqWithName.SourceSandboxName && !sandboxReqWithName.SourceId) {
+      // error - we need SourceSandboxName or SourceID to know which sandbox to clone from
       throw new SfError(
-        cloneMessages.getMessage('missingSourceSandboxName', ['SourceSandboxName']),
-        cloneMessages.getMessage('missingSourceSandboxNameAction', ['SourceSandboxName'])
+        cloneMessages.getMessage('missingSourceSandboxNameORSourceId'),
+        cloneMessages.getMessage('missingSourceSandboxNameORSourceIdAction')
       );
     }
-    return { sandboxReq, srcSandboxName: SourceSandboxName };
+    return { sandboxReq, srcSandboxName: SourceSandboxName, srcId: SourceId };
   } else {
     if (!sandboxReq.LicenseType) {
       return { sandboxReq: { ...sandboxReq, LicenseType: SandboxLicenseType.developer } };
@@ -122,10 +132,22 @@ export async function getUserGroupIdByName(conn: Connection, groupName: string):
     throw cloneMessages.createError('error.userGroupQueryFailed', [groupName], [], err as Error);
   }
 }
+export async function getSrcIdByName(conn: Connection, sandboxName: string): Promise<string | undefined> {
+  try {
+    const result = (
+      await conn.singleRecordQuery(`SELECT id FROM SandboxInfo WHERE SandboxName = '${sandboxName}'`, { tooling: true })
+    ).Id;
+    return result;
+  } catch (err) {
+    throw cloneMessages.createError('error.sandboxNameQueryFailed', [sandboxName], [], err as Error);
+  }
+}
+
 export default {
   createSandboxRequest,
   generateSboxName,
   readSandboxDefFile,
   getApexClassIdByName,
   getUserGroupIdByName,
+  getSrcIdByName,
 };