feat: add env commands for create/resume scratch/sandbox orgs

.circleci/config.yml

@@ -65,6 +65,16 @@ workflows:
           context:
             - na40-auth-url
             - na40-jwt
+      - release-management/run-command-keyword:
+          name: sandbox-nuts
+          git_key_word: '[sb-nuts]'
+          timeout: 1.5h
+          command: test:nuts:sandbox
+          requires:
+            - release-management/test-nut
+          context:
+            - na40-auth-url
+            - na40-jwt
       - release-management/release-package:
           context:
             - AWS

command-snapshot.json

@@ -1,10 +1,30 @@
 [
+  {
+    "command": "env:create:sandbox",
+    "plugin": "@salesforce/plugin-env",
+    "flags": [
+      "alias",
+      "async",
+      "clone",
+      "definition-file",
+      "json",
+      "license-type",
+      "name",
+      "no-prompt",
+      "poll-interval",
+      "set-default",
+      "target-org",
+      "wait"
+    ],
+    "alias": []
+  },
   {
     "command": "env:create:scratch",
     "plugin": "@salesforce/plugin-env",
     "flags": [
       "alias",
       "api-version",
+      "async",
       "client-id",
       "definition-file",
       "duration-days",
@@ -47,5 +67,17 @@
     "plugin": "@salesforce/plugin-env",
     "flags": ["browser", "json", "path", "target-env", "url-only"],
     "alias": []
+  },
+  {
+    "command": "env:resume:sandbox",
+    "plugin": "@salesforce/plugin-env",
+    "flags": ["job-id", "json", "name", "target-org", "use-most-recent", "wait"],
+    "alias": []
+  },
+  {
+    "command": "env:resume:scratch",
+    "plugin": "@salesforce/plugin-env",
+    "flags": ["job-id", "json", "use-most-recent"],
+    "alias": []
   }
 ]

messages/create.sandbox.md

@@ -0,0 +1,129 @@
+# summary
+
+Create a sandbox org.
+
+# description
+
+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.
+
+# examples
+
+- Create a sandbox org using a definition file and give it the alias "MyDevSandbox". The production org that contains the sandbox license has the alias "prodOrg".
+
+  <%= config.bin %> <%= command.id %> -f config/dev-sandbox-def.json --alias MyDevSandbox --target-org prodOrg
+
+- Create a sandbox org by directly specifying its name and type of license (Developer) instead of using a definition file. Set the sandbox org as your default.
+
+  <%= config.bin %> <%= command.id %> --name mysandbox --license-type Developer --alias MyDevSandbox --target-org prodOrg --set-default
+
+# flags.setDefault.summary
+
+Set the sandbox org as your default org.
+
+# flags.alias.summary
+
+Alias for the sandbox org.
+
+# flags.alias.description
+
+When you create a sandbox, the generated usernames are based on the usernames present in the production org. To ensure uniqueness, the new usernames are appended with the name of the sandbox. For example, the username "[email protected]" in the production org results in the username "[email protected]" in a sandbox named "mysandbox". When you set an alias for a sandbox org, it's assigned to the resulting username of the user running this command.
+
+# flags.targetOrg.summary
+
+Username or alias of the production org that contains the sandbox license.
+
+# flags.targetOrg.description
+
+When it creates the sandbox org, Salesforce copies the metadata, and optionally data, from your production org to the new sandbox org.
+
+# flags.definitionFile.summary
+
+Path to a sandbox definition file.
+
+# flags.definitionFile.description
+
+The sandbox definition file is a blueprint for the sandbox. You can create different definition files for each sandbox type that you use in the development process. See https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_sandbox_definition.htm for all the options you can specify in the defintion file.
+
+# flags.name.summary
+
+Name of the sandbox org.
+
+# flags.name.description
+
+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
+
+Name of the sandbox org to clone.
+
+# flags.clone.description
+
+The value of clone must be an existing sandbox in the same target-org.
+
+# flags.licenseType.summary
+
+Type of sandbox license.
+
+# flags.wait.summary
+
+Number of minutes to wait for the sandbox org to be ready.
+
+# flags.wait.description
+
+If the command continues to run after the wait period, the CLI returns control of the terminal to you and displays the "sf env resume sandbox" command you run to check the status of the create. The displayed command includes the job ID for the running sandbox creation.
+
+# flags.poll-interval.summary
+
+Number of seconds to wait between retries.
+
+# flags.async.summary
+
+Request the sandbox creation, but don't wait for it to complete.
+
+# flags.async.description
+
+The command immediately displays the job ID and returns control of the terminal to you. This way, you can continue to use the CLI. To check the status of the sandbox creation, run "sf env resume sandbox".
+
+# flags.noPrompt.summary
+
+Don't prompt for confirmation about the sandbox configuration.
+
+# isConfigurationOk
+
+Is the configuration correct?
+
+# warning.NoSandboxNameDefined
+
+No SandboxName defined, generating new SandboxName: %s.
+
+# error.RequiresTargetOrg
+
+This command requires a target-org. Specify it with the --target-org flag or by running the "sf config set target-org=<username>" command.
+
+# error.MissingLicenseType
+
+The sandbox license type is required, but you didn't provide a value. Specify the license type in the sandbox definition file with the "licenseType" option, or specify the --license-type and --name flags at the command-line. See https://developer.salesforce.com/docs/atlas.en-us.sf_dev.meta/sf_dev/sf_dev_sandbox_definition.htm for more information.
+
+# error.NoConfig
+
+Specify either a sandbox definition file or the --name and --license-type flags together.
+
+# error.SandboxNameLength
+
+The sandbox name "%s" should be 10 or fewer characters.
+
+# error.UserNotSatisfiedWithSandboxConfig
+
+The sandbox request configuration isn't acceptable.
+
+# error.pollIntervalGreaterThanWait
+
+The poll interval (%d seconds) can't be larger that wait (%d in seconds).
+
+# error.CreateTimeout
+
+The wait timeout (%d minutes) has expired. Check command results for more information.
+
+# error.noCloneSource
+
+Could not find the clone sandbox name "%s" in the target org.

messages/create_scratch.md

@@ -46,6 +46,14 @@ Don't include second-generation managed package (2GP) ancestors in the scratch o
 
 Salesforce edition of the scratch org.
 
+# flags.async.summary
+
+Request the org, but don't wait for it to complete.
+
+# flags.async.description
+
+The command immediately displays the job ID and returns control of the terminal to you. This way, you can continue to use the CLI. To resume the scratch org creation, run "sf env resume scratch".
+
 # flags.edition.description
 
 The editions that begin with "partner-" are available only if the Dev Hub org is a Partner Business Org.
@@ -66,6 +74,10 @@ Consumer key of the Dev Hub connected app.
 
 Number of minutes to wait for the scratch org to be ready.
 
+# flags.wait.description
+
+If the command continues to run after the wait period, the CLI returns control of the terminal to you and displays the job ID. To resume the scratch org creation, run the env resume scratch command and pass it the job ID.
+
 # flags.track-source.description
 
 We recommend you enable source tracking in scratch orgs, which is why it's the default behavior. Source tracking allows you to track the changes you make to your metadata, both in your local project and in the scratch org, and to detect any conflicts between the two.
@@ -87,3 +99,7 @@ OAuth client secret of your personal connected app
 # success
 
 Your scratch org is ready.
+
+# action.resume
+
+Resume scratch org creation by running sf env resume scratch --job-id %s

messages/delete_sandbox.md

@@ -35,3 +35,7 @@ Are you sure you want to delete the sandbox with name: %s?
 # success
 
 Successfully marked sandbox %s for deletion.
+
+# error.isNotSandbox
+
+The target org, %s, is not a sandbox.

messages/resume.sandbox.md

@@ -0,0 +1,87 @@
+# summary
+
+Check the status of a sandbox creation, and log in to it if it's ready.
+
+# description
+
+Sandbox creation can take a long time. If the original "sf env create sandbox" command either times out, or you specified the --async flag, the command displays a job ID. Use this job ID to check whether the sandbox creation is complete, and if it is, the command then logs into it.
+
+You can also use the sandbox name to check the status or the --use-most-recent flag to use the job ID of the most recent sandbox creation.
+
+# examples
+
+- Check the status of a sandbox creation using its name and specify a production org with alias "prodOrg":
+
+  <%= config.bin %> <%= command.id %> --name mysandbox --target-org prodOrg
+
+- Check the status using the job ID:
+
+  <%= config.bin %> <%= command.id %> --job-id 0GRxxxxxxxx
+
+- Check the status of the most recent sandbox create request:
+
+  <%= config.bin %> <%= command.id %> --use-most-recent
+
+# flags.setDefault.summary
+
+Set the sandbox org as your default org.
+
+# flags.id.summary
+
+Job ID of the incomplete sandbox creation that you want to check the status of.
+
+# flags.id.description
+
+The job ID is valid for 24 hours after you start the sandbox creation.
+
+# flags.alias.summary
+
+Alias for the sandbox org.
+
+# flags.alias.description
+
+When you create a sandbox, the generated usernames are based on the usernames present in the production org. To ensure uniqueness, the new usernames are appended with the name of the sandbox. For example, the username "[email protected]" in the production org results in the username "[email protected]" in a sandbox named "mysandbox". When you set an alias for a sandbox org, it's assigned to the resulting username of the user running this command.
+
+# flags.targetOrg.summary
+
+Username or alias of the production org that contains the sandbox license.
+
+# flags.targetOrg.description
+
+When it creates the sandbox org, Salesforce copies the metadata, and optionally data, from your production org to the new sandbox org.
+
+# flags.name.summary
+
+Name of the sandbox org.
+
+# flags.wait.summary
+
+Number of minutes to wait for the sandbox org to be ready.
+
+# flags.wait.description
+
+If the command continues to run after the wait period, the CLI returns control of the terminal window to you and returns the job ID. To resume checking the sandbox creation, rerun this command.
+
+# flags.use-most-recent.summary
+
+Use the most recent sandbox create request.
+
+# error.pollIntervalGreaterThanWait
+
+The poll interval (%d seconds) can't be larger that wait (%d in seconds).
+
+# error.NoSandboxNameOrJobId
+
+No sandbox name or job ID were provided.
+
+# error.LatestSandboxRequestNotFound
+
+Retry the command using either the --name or --job-id flags.
+
+#error.NoSandboxRequestFound
+
+Couldn't find a sandbox creation request using the provided sandbox name or job ID.
+
+# error.ResumeTimeout
+
+The wait timeout (%d minutes) has expired. Check command results for more information.

messages/resume_scratch.md

@@ -0,0 +1,41 @@
+# summary
+
+Resume the creation of an incomplete scratch org.
+
+# description
+
+When the original "sf env create scratch" command either times out or is run with the --async flag, it displays a job ID.
+
+Run this command by either passing it a job ID or using the --use-most-recent flag to specify the most recent incomplete scratch org.
+
+# examples
+
+- Resume a scratch org create with a job ID:
+
+  <%= config.bin %> <%= command.id %> --job-id 2SR3u0000008fBDGAY
+
+- Resume your most recent incomplete scratch org:
+
+  <%= config.bin %> <%= command.id %> --use-most-recent
+
+# flags.job-id.summary
+
+Job ID of the incomplete scratch org create that you want to resume.
+
+# flags.job-id.description
+
+The job ID is the same as the record ID of the incomplete scratch org in the ScratchOrgInfo object of the Dev Hub.
+
+The job ID is valid for 24 hours after you start the scratch org creation.
+
+# flags.use-most-recent.summary
+
+Use the job ID of the most recent incomplete scratch org. 
+
+# error.NoRecentJobId
+
+There are no recent job IDs (ScratchOrgInfo requests) in your cache. Maybe it completed or already resumed?
+
+# success
+
+Your scratch org is ready.