Merge pull request #1358 from salesforcecli/sl/W-16857079

feat: W-16857079 - add a --snapshot flag for creating scratch org

Author: shetzel

command-snapshot.json

@@ -27,7 +27,7 @@
     "alias": ["env:create:scratch"],
     "command": "org:create:scratch",
     "flagAliases": [],
-    "flagChars": ["a", "c", "d", "e", "f", "i", "m", "t", "v", "w", "y"],
+    "flagChars": ["a", "c", "d", "e", "f", "i", "m", "s", "t", "v", "w", "y"],
     "flags": [
       "admin-email",
       "alias",
@@ -45,6 +45,7 @@
       "no-namespace",
       "release",
       "set-default",
+      "snapshot",
       "source-org",
       "target-dev-hub",
       "track-source",

messages/create_scratch.md

@@ -4,19 +4,24 @@ Create a scratch org.
 
 # description
 
-There are two ways to create a scratch org: either specify a definition file that contains the options or use the --edition flag to specify the one required option.
+There are four ways to create a scratch org:
 
-For either method, you can also use these flags; if you use them with --definition-file, they override their equivalent option in the scratch org definition file:
+    * Specify a definition file that contains the scratch org options.
+    * Use the --edition flag to specify the one required option; this method doesn't require a defintion file.
+    * Use the --snapshot flag to create a scratch org from a snapshot. Snapshots are a point-in-time copy of a scratch org; you create a snapshot with the "sf org create snapshot" command.
+    * Use the --source-org flag to create a scratch org from an org shape. Org shapes mimic the baseline setup of a source org without the extraneous data and metadata; you create an org shape with the "sf org create shape" command.
+
+The --edition, --snapshot, and --source-org flags are mutually exclusive, which means if you specify one, you can't also specify the others.
+
+For any of the methods, you can also use these flags; if you use them with --definition-file, they override their equivalent option in the scratch org definition file:
 
     * --description
     * --name  (equivalent to the "orgName" option)
     * --username
     * --release
-    * --edition
     * --admin-email (equivalent to the "adminEmail" option)
-    * --source-org (equivalent to the "sourceOrg" option)
 
-If you want to set options other than the preceding ones, such as org features or settings, you must use a definition file.
+If you want to set options such as org features or settings, you must use a definition file.
 
 You must specify a Dev Hub to create a scratch org, either with the --target-dev-hub flag or by setting your default Dev Hub with the target-dev-hub configuration variable.
 
@@ -34,6 +39,10 @@ You must specify a Dev Hub to create a scratch org, either with the --target-dev
 
   <%= config.bin %> <%= command.id %> --edition enterprise --alias my-scratch-org --target-dev-hub MyHub --release preview
 
+- Create a scratch org from a snapshot called "NightlyBranch"; be sure you specify the same Dev Hub org associated with the snapshot. We recommend you increase the --wait time because creating a scratch org from a snapshot can take a while:
+
+  <%= config.bin %> <%= command.id %> --alias my-scratch-org --target-dev-hub MyHub --snapshot NightlyBranch --wait 10
+
 # flags.target-dev-hub.summary
 
 Username or alias of the Dev Hub org.
@@ -62,6 +71,14 @@ Don't include second-generation managed package (2GP) ancestors in the scratch o
 
 Salesforce edition of the scratch org. Overrides the value of the "edition" option in the definition file, if set.
 
+# flags.snapshot.summary
+
+Name of the snapshot to use when creating this scratch org. Overrides the value of the "snapshot" option in the defintion file, if set.
+
+# flags.snapshot.description
+
+To view the names of the available snapshots for a given Dev Hub org, run the "sf org list snapshot" command.
+
 # flags.async.summary
 
 Request the org, but don't wait for it to complete.
@@ -92,7 +109,11 @@ Email address that will be applied to the org's admin user. Overrides the value
 
 # flags.source-org.summary
 
-15-character ID of the org whose shape the new scratch org will be based on. Overrides the value of the "sourceOrg" option in the definition file, if set.
+15-character ID of the org shape that the new scratch org is based on. Overrides the value of the "sourceOrg" option in the definition file, if set.
+
+# flags.source-org.description
+
+To view the names of the available org shapes for a given Dev Hub org, run the "sf org list shape" command.
 
 # flags.wait.summary
 

src/commands/org/create/scratch.ts

@@ -80,6 +80,7 @@ export default class OrgCreateScratch extends SfCommand<ScratchCreateResponse> {
         'partner-group',
         'partner-professional',
       ],
+      exclusive: ['snapshot', 'source-org'],
       // eslint-disable-next-line @typescript-eslint/require-await
       parse: async (value: string) => {
         // the API expects partner editions in `partner <EDITION>` format.
@@ -91,6 +92,13 @@ export default class OrgCreateScratch extends SfCommand<ScratchCreateResponse> {
       },
       helpGroup: definitionFileHelpGroupName,
     }),
+    snapshot: Flags.string({
+      char: 's',
+      summary: messages.getMessage('flags.snapshot.summary'),
+      description: messages.getMessage('flags.snapshot.description'),
+      exclusive: ['edition', 'source-org'],
+      helpGroup: definitionFileHelpGroupName,
+    }),
     'no-namespace': Flags.boolean({
       char: 'm',
       summary: messages.getMessage('flags.no-namespace.summary'),
@@ -151,6 +159,8 @@ export default class OrgCreateScratch extends SfCommand<ScratchCreateResponse> {
     }),
     'source-org': Flags.salesforceId({
       summary: messages.getMessage('flags.source-org.summary'),
+      description: messages.getMessage('flags.source-org.description'),
+      exclusive: ['edition', 'snapshot'],
       startsWith: '00D',
       length: 15,
       helpGroup: definitionFileHelpGroupName,

src/shared/scratchOrgRequest.ts

@@ -10,10 +10,12 @@ import { Interfaces } from '@oclif/core';
 import { ScratchOrgCreateOptions } from '@salesforce/core';
 import { Duration } from '@salesforce/kit';
 import EnvCreateScratch from '../commands/org/create/scratch.js';
+
 /**
  * Provide the parsed flags
  * Returns the objet necessary to create a scratch org
  */
+
 export const buildScratchOrgRequest = async (
   flags: Interfaces.InferredFlags<typeof EnvCreateScratch.flags>,
   clientSecret?: string
@@ -23,6 +25,7 @@ export const buildScratchOrgRequest = async (
       ? (JSON.parse(await fs.promises.readFile(flags['definition-file'], 'utf-8')) as Record<string, unknown>)
       : {}),
     ...(flags.edition ? { edition: flags.edition } : {}),
+    ...(flags.snapshot ? { snapshot: flags.snapshot } : {}),
     ...(flags.username ? { username: flags.username } : {}),
     ...(flags.description ? { description: flags.description } : {}),
     ...(flags.name ? { orgName: flags.name } : {}),

test/shared/scratchOrgRequest.test.ts

@@ -41,6 +41,13 @@ describe('buildScratchOrgRequest function', () => {
     expect(result.orgConfig).to.deep.equal({ edition: 'developer' });
   });
 
+  it('snapshot as only flag', async () => {
+    const flags = await paramsToFlags(['--snapshot', 'my-snapshot-name']);
+    const result = await buildScratchOrgRequest(flags);
+    expect(result.durationDays).to.equal(7);
+    expect(result.orgConfig).to.deep.equal({ snapshot: 'my-snapshot-name' });
+  });
+
   describe('source-org', () => {
     it('valid source-org as only flag', async () => {
       const flags = await paramsToFlags(['--source-org', '00D123456789012']);