Sm/display tracking info (#290)

* feat: supports source tracking for deploy/retrieve

* fix: existing mpd nuts ignore tracking conflicts

* chore: deps

* test: nuts from plugin-source

* test(wip): remoteChanges nut fails until plugin-source PO merges (sfdx/sf folder)

* feat: ignoreConflicts for validate

* Update messages/deploy.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/retrieve.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/deploy.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/deploy.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/deploy.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/deploy.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/retrieve.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/deploy.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/retrieve.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/retrieve.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/retrieve.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/retrieve.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* Update messages/retrieve.metadata.md

Co-authored-by: Juliet Shackell <[email protected]>

* chore: bump plugins

* chore: bump lint rules and sdr (for events)

* refactor: linter fixes

* test: lwc nut and pjson script

* test: factor out ebikes deploy count

* fix: no tracking on validate/quick

* feat: preview metadata (missing ignored on non-push)

* feat: ignores work for source/manifest/etc

* feat: retrieve preview (for changes only)

* test: nuts for preview

* chore: bump oclif/core

* test: 2 nuts use status AND preview

* test: working except remote deletes

* feat: wip for showing pulled deletes

* fix: review messages for "sf deploy metadata preview"

* fix: shared preview messages

* fix: messages for sf retrieve metadata preview

* fix: edit

* docs: text fixes from Juliet

* fix: display deleted files on retrieve

* chore: schema

* docs: oclif subtopic

* chore: use changes in STL

* chore: deps

* Edit preview messages (#315)

* fix: edit shared preview messages.

* fix: quick edit

* Update retrieve.metadata.preview.md

* Update deploy.metadata.md

* Update deploy.metadata.validate.md

* edit

* refactor: pr feedback 1

* refactor: remove unnecessary type

* chore: dedupe deps

* refactor: one map, with more if else return {} (#316)

* refactor: one map, with more if else return {}

* refactor: if/else from PR comments

* fix: retrieve needs an stl for conflicts

* test: nuts for preview --ignore-conflicts

* test: nuts for conflict preview options

Co-authored-by: Juliet Shackell <[email protected]>

Author: mshanemc

command-snapshot.json

@@ -36,6 +36,12 @@
     "flags": ["async", "job-id", "json", "use-most-recent", "wait"],
     "alias": []
   },
+  {
+    "command": "deploy:metadata:preview",
+    "plugin": "@salesforce/plugin-deploy-retrieve",
+    "flags": ["ignore-conflicts", "json", "manifest", "metadata", "source-dir", "target-org"],
+    "alias": []
+  },
   {
     "command": "deploy:metadata:quick",
     "plugin": "@salesforce/plugin-deploy-retrieve",
@@ -90,5 +96,11 @@
       "wait"
     ],
     "alias": []
+  },
+  {
+    "command": "retrieve:metadata:preview",
+    "plugin": "@salesforce/plugin-deploy-retrieve",
+    "flags": ["ignore-conflicts", "json", "target-org"],
+    "alias": []
   }
 ]

messages/deploy.metadata.md

@@ -156,7 +156,7 @@ Target API version for the deploy.
 
 # flags.api-version.description
 
-Use this flag to override the default API version, which is the latest version supported the CLI, with the API version of your package.xml file.
+Use this flag to override the default API version with the API version of your package.xml file. The default API version is the latest version supported by the CLI.
 
 # flags.async.summary
 
@@ -204,3 +204,11 @@ There are changes in the org that conflict with the local changes you're trying
 - To overwrite the remote changes, rerun this command with the --ignore-conflicts flag.
 
 - To overwrite the local changes, run the "sf retrieve metadata" command with the --ignore-conflicts flag.
+
+# error.nothingToDeploy
+
+No local changes to deploy.
+
+# error.nothingToDeploy.Actions
+
+- To see conflicts and ignored files, run "sf deploy metadata preview" with any of the manifest, directory, or metadata flags.

messages/deploy.metadata.preview.md

@@ -0,0 +1,93 @@
+# summary
+
+Preview a deployment to see what will deploy to the org, the potential conflicts, and the ignored files.
+
+# description
+
+You must run this command from within a project.
+
+The command outputs a table that describes what will happen if you run the "sf deploy metadata" command. The table lists the metadata components that will be deployed and deleted. The table also lists the current conflicts between files in your local project and components in the org. Finally, the table lists the files that won't be deployed because they're included in your .forceignore file.
+
+If your org allows source tracking, then this command considers conflicts between the org and local. Some orgs, such as production orgs, never allow source tracking. Use the "--no-track-source" flag when you create a scratch or sandbox org to disable source tracking.
+
+To preview the deployment of multiple metadata components, either set multiple --metadata <name> flags or a single --metadata flag with multiple names separated by spaces. Enclose names that contain spaces in one set of double quotes. The same syntax applies to --manifest and --source-dir.
+
+# examples
+
+- NOTE: The commands to preview a deployment and actually deploy it use similar flags. We provide a few preview examples here, but see the help for "sf deploy metadata" for more examples that you can adapt for previewing.
+
+- Preview the deployment of source files in a directory, such as force-app:
+
+      <%= config.bin %> <%= command.id %>  --source-dir force-app
+
+- Preview the deployment of all Apex classes:
+
+      <%= config.bin %> <%= command.id %> --metadata ApexClass
+
+- Preview deployment of a specific Apex class:
+
+      <%= config.bin %> <%= command.id %> --metadata ApexClass:MyApexClass
+
+- Preview deployment of all components listed in a manifest:
+
+      <%= config.bin %> <%= command.id %> --manifest path/to/package.xml
+
+# flags.target-org.summary
+
+Login username or alias for the target org.
+
+# flags.target-org.description
+
+Overrides your default org.
+
+# flags.metadata.summary
+
+Metadata component names to preview.
+
+# flags.source-dir.summary
+
+Path to the local source files to preview.
+
+# flags.source-dir.description
+
+The supplied path can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all metadata types in the directory and its subdirectories).
+
+If you specify this flag, don’t specify --metadata or --manifest.
+
+# flags.manifest.summary
+
+Full file path for manifest (package.xml) of components to preview.
+
+# flags.manifest.description
+
+All child components are included. If you specify this flag, don’t specify --metadata or --source-dir.
+
+# flags.ignore-conflicts.summary
+
+Ignore conflicts and deploy local files, even if they overwrite changes in the org.
+
+# flags.ignore-conflicts.description
+
+This flag applies only to orgs that allow source tracking. It has no effect on orgs that don't allow it, such as production orgs.
+
+# flags.concise.summary
+
+Omit ignored files.
+
+# flags.api-version.summary
+
+Target API version for the preview.
+
+# flags.api-version.description
+
+Use this flag to override the default API version with the API version of your package.xml file. The default API version is the latest version supported by the CLI.
+
+# error.Conflicts
+
+There are changes in the org that conflict with the local changes you're trying to preview.
+
+# error.Conflicts.Actions
+
+- To overwrite the remote changes, rerun this command with the --ignore-conflicts flag.
+
+- To overwrite the local changes, run the "sf retrieve metadata" command with the --ignore-conflicts flag.

messages/deploy.metadata.validate.md

@@ -104,7 +104,7 @@ Target API version for the validation.
 
 # flags.api-version.description
 
-Use this flag to override the default API version, which is the latest version supported the CLI, with the API version in your package.xml file.
+Use this flag to override the default API version with the API version of your package.xml file. The default API version is the latest version supported by the CLI.
 
 # flags.async.summary
 

messages/previewMessages.md

@@ -0,0 +1,39 @@
+# conflicts.none
+
+No conflicts found.
+
+# conflicts.header
+
+Conflicts [%s]. Run the command with the --ignore-conflicts flag to override.
+
+# ignored.none
+
+No files were ignored. Update your your .forceignore file if you want to ignore certain files.
+
+# ignored.header
+
+Ignored [%s] files. These files won't %s because they're ignored by your .forceignore file.
+
+# deploy.header
+
+Will Deploy [%s] files.
+
+# deploy.none
+
+No files will be deployed.
+
+# retrieve.header
+
+Will Retrieve [%s] files.
+
+# retrieve.none
+
+No files will be retrieved.
+
+# delete.header
+
+Will Delete [%s] files.
+
+# delete.none
+
+No files will be deleted.

messages/retrieve.metadata.preview.md

@@ -0,0 +1,59 @@
+# summary
+
+Preview a retrieval to see what will be retrieved from the org, the potential conflicts, and the ignored files.
+
+# description
+
+You must run this command from within a project.
+
+The command outputs a table that describes what will happen if you run the "sf retrieve metadata" command. The table lists the metadata components that will be retrieved and deleted. The table also lists the current conflicts between files in your local project and components in the org. Finally, the table lists the files that won't be retrieved because they're included in your .forceignore file.
+
+If your org allows source tracking, then this command considers conflicts between the org and local. Some orgs, such as production orgs, never allow source tracking. Use the "--no-track-source" flag when you create a scratch or sandbox org to disable source tracking.
+
+# examples
+
+- Preview the retrieve of all changes from the org:
+
+  <%= config.bin %> <%= command.id %>
+
+- Preview the retrieve when ignoring any conflicts:
+
+  <%= config.bin %> <%= command.id %> --ignore-conflicts
+
+# flags.target-org.summary
+
+Login username or alias for the target org.
+
+# flags.target-org.description
+
+Overrides your default org.
+
+# flags.ignore-conflicts.summary
+
+Ignore conflicts and preview the retrieve of remote components, even if they will overwrite local changes.
+
+# flags.ignore-conflicts.description
+
+This flag applies only to orgs that allow source tracking. It has no effect on orgs that don't allow it, such as production orgs.
+
+# flags.concise.summary
+
+Omit ignored files.
+
+# flags.api-version.summary
+
+Target API version for the deploy.
+
+# flags.api-version.description
+
+Use this flag to override the default API version with the API version of your package.xml file. The default API version is the latest version supported by the CLI.
+
+# error.Conflicts
+
+There are local changes that conflict with the remote changes that would be retrieved.
+
+# error.Conflicts.Actions
+
+- To overwrite the remote changes, run the "sf deploy metadata" command with the --ignore-conflicts flag.
+
+- To overwrite the local changes, run the "sf retrieve metadata" command with the --ignore-conflicts flag.

package.json

@@ -114,7 +114,12 @@
         }
       },
       "retrieve": {
-        "description": "Commands to retrieve artifacts from an environment."
+        "description": "Commands to retrieve artifacts from an environment.",
+        "subtopics": {
+          "metadata": {
+            "description": "Commands to retrieve metadata from a Salesforce org."
+          }
+        }
       }
     }
   },

schemas/deploy-metadata-preview.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/PreviewResult",
+  "definitions": {
+    "PreviewResult": {
+      "type": "object",
+      "properties": {
+        "ignored": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PreviewFile"
+          }
+        },
+        "conflicts": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PreviewFile"
+          }
+        },
+        "toDeploy": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PreviewFile"
+          }
+        },
+        "toDelete": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PreviewFile"
+          }
+        },
+        "toRetrieve": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PreviewFile"
+          }
+        }
+      },
+      "required": ["ignored", "conflicts", "toDeploy", "toDelete", "toRetrieve"],
+      "additionalProperties": false
+    },
+    "PreviewFile": {
+      "type": "object",
+      "properties": {
+        "fullName": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "conflict": {
+          "type": "boolean"
+        },
+        "ignored": {
+          "type": "boolean"
+        },
+        "path": {
+          "type": "string"
+        },
+        "projectRelativePath": {
+          "type": "string"
+        },
+        "operation": {
+          "type": "string",
+          "enum": ["deploy", "retrieve", "deletePost", "deletePre"]
+        }
+      },
+      "required": ["fullName", "type", "conflict", "ignored"],
+      "additionalProperties": false
+    }
+  }
+}