feat: add --dry-run flag to apply command

The probably unused plan command and related flags on the apply command like --planfile and --statefile have been removed in favor of a --dry-run flag on the apply command.

BREAKING CHANGE: The plan command has been removed.

Use "apply --dry-run" instead.

Author: amtrack

README.md

@@ -44,7 +44,7 @@ Apply the config:
 ```console
 $ sf browserforce apply -f ./config/currency.json --target-org myOrg@example.com
   logging in... done
-  Applying definition file ./config/currency.json to org myOrg@example.com
+  Applying config file ./config/currency.json to org myOrg@example.com
   [CompanyInformation] retrieving state... done
   [CompanyInformation] changing 'defaultCurrencyIsoCode' to '"English (South Africa) - ZAR"'... done
   logging out... done

src/browserforce-command.ts

@@ -12,18 +12,12 @@ export abstract class BrowserforceCommand<T> extends SfCommand<T> {
     'target-org': Flags.requiredOrg(),
     definitionfile: Flags.string({
       char: 'f',
-      description: 'path to a browserforce state file',
+      description: 'path to a browserforce config file',
     }),
-    planfile: Flags.string({
-      char: 'p',
-      name: 'plan',
-      description: 'path to a browserforce plan file',
-    }),
-    statefile: Flags.string({
-      char: 's',
-      name: 'state',
-      description:
-        'path to a browserforce definition file\nThe schema is similar to the scratch org definition file.\nSee https://github.com/amtrack/sfdx-browserforce-plugin#supported-org-preferences for supported values.',
+    'dry-run': Flags.boolean({
+      char: 'd',
+      description: 'dry run',
+      env: 'BROWSERFORCE_DRY_RUN',
     }),
   };
   protected bf: Browserforce;
@@ -40,7 +34,7 @@ export abstract class BrowserforceCommand<T> extends SfCommand<T> {
       try {
         definition = JSON.parse(definitionFileData);
       } catch (err) {
-        throw new Error('Failed parsing definitionfile');
+        throw new Error('Failed parsing config file');
       }
     }
     handleDeprecations(definition);

src/commands/browserforce/apply.ts

@@ -5,11 +5,11 @@ type BrowserforceApplyResponse = {
 };
 
 export class BrowserforceApply extends BrowserforceCommand<BrowserforceApplyResponse> {
-  public static description = 'apply a plan from a definition file';
+  public static description = 'apply a plan from a config file';
   public static examples = [
     `$ <%= config.bin %> <%= command.id %> -f ./config/currency.json --target-org myOrg@example.com
   logging in... done
-  Applying definition file ./config/currency.json to org myOrg@example.com
+  Applying config file ./config/currency.json to org myOrg@example.com
   [CompanyInformation] retrieving state... done
   [CompanyInformation] changing 'defaultCurrencyIsoCode' to '"English (South Africa) - ZAR"'... done
   logging out... done
@@ -18,7 +18,7 @@ export class BrowserforceApply extends BrowserforceCommand<BrowserforceApplyResp
 
   public async run(): Promise<BrowserforceApplyResponse> {
     const { flags } = await this.parse(BrowserforceApply);
-    this.log(`Applying definition file ${flags.definitionfile} to org ${flags['target-org'].getUsername()}`);
+    this.log(`Applying config file ${flags.definitionfile} to org ${flags['target-org'].getUsername()}`);
     for (const setting of this.settings) {
       const driver = setting.Driver;
       const instance = new driver(this.bf);
@@ -32,21 +32,24 @@ export class BrowserforceApply extends BrowserforceCommand<BrowserforceApplyResp
       }
       this.spinner.stop();
       const diff = instance.diff(state, setting.value);
+      const action = flags['dry-run'] ? 'would change' : 'changing';
       if (diff !== undefined) {
         this.spinner.start(
           `[${driver.name}] ${Object.keys(diff)
             .map((key) => {
-              return `changing '${key}' to '${JSON.stringify(diff[key])}'`;
+              return `${action} '${key}' to '${JSON.stringify(diff[key])}'`;
             })
             .join('\n')}`,
         );
-        try {
-          await instance.apply(diff);
-        } catch (err) {
-          this.spinner.stop('failed');
-          throw err;
+        if (!flags['dry-run']) {
+          try {
+            await instance.apply(diff);
+          } catch (err) {
+            this.spinner.stop('failed');
+            throw err;
+          }
+          this.spinner.stop();
         }
-        this.spinner.stop();
       } else {
         this.log(`[${driver.name}] no action necessary`);
       }

src/commands/browserforce/plan.ts

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/amtrack/sfdx-browserforce-plugin/src/plugins/schema.json",
-  "title": "Browserforce Definition Configuration",
-  "description": "The browserforce definition file contains the configuration values that defines browser automation tasks for Salesforce orgs.",
+  "title": "Browserforce Configuration",
+  "description": "The browserforce config file contains the configuration values that defines browser automation tasks for Salesforce orgs.",
   "type": "object",
   "properties": {
     "settings": {

src/plugins/schema.json

@@ -4,7 +4,7 @@ import * as DRIVERS from '../src/plugins/index.js';
 
 describe('ConfigParser', () => {
   describe('parse()', () => {
-    it('should parse a valid definition file', () => {
+    it('should parse a valid config file', () => {
       const definition = {
         settings: {
           security: {},
@@ -13,7 +13,7 @@ describe('ConfigParser', () => {
       const result = ConfigParser.parse(DRIVERS, definition);
       assert.deepStrictEqual(result[0].Driver.name, 'Security');
     });
-    it('should fail parsing an invalid definition file', () => {
+    it('should fail parsing an invalid config file', () => {
       const definition = {
         foo: {
           bar: {
@@ -27,7 +27,7 @@ describe('ConfigParser', () => {
         ConfigParser.parse(DRIVERS, anonymousDefinition);
       }, /Missing 'settings' attribute in definition:/);
     });
-    it('should fail parsing a definition file with an invalid plugin', () => {
+    it('should fail parsing a config file with an invalid plugin', () => {
       const definition = {
         settings: {
           foo: {