Sh/mdapi retrieve (#383)

* feat: add force:mdapi:beta:retrieve * feat: add force:mdapi:beta:retrieve:report and stash * fix: ensure sourcepath and packagenames exclusivity * fix: snapshot updates and small fixes * fix: updates for stash rewrite * chore: lint fixes * fix: review comment updates * fix: wait param help and stash jobid retrieval * fix: append .zip to zipfiles without extensions * fix: append .zip to zipfiles without extensions * fix: unit test caught some bad logic * fix: add unit tests for retrieve * fix: improved doc
salesforcecli · Jan 13, 2022 · c61321a · c61321a
1 parent 3258975
commit c61321a
Show file tree

Hide file tree

Showing 19 changed files with 1,457 additions and 103 deletions.
diff --git a/command-snapshot.json b/command-snapshot.json
@@ -36,6 +36,41 @@
     "plugin": "@salesforce/plugin-source",
     "flags": ["apiversion", "jobid", "json", "loglevel", "targetusername", "wait"]
   },
+  {
+    "command": "force:mdapi:beta:retrieve",
+    "plugin": "@salesforce/plugin-source",
+    "flags": [
+      "apiversion",
+      "json",
+      "loglevel",
+      "packagenames",
+      "retrievetargetdir",
+      "singlepackage",
+      "sourcedir",
+      "targetusername",
+      "unpackaged",
+      "unzip",
+      "verbose",
+      "wait",
+      "zipfilename"
+    ]
+  },
+  {
+    "command": "force:mdapi:beta:retrieve:report",
+    "plugin": "@salesforce/plugin-source",
+    "flags": [
+      "apiversion",
+      "jobid",
+      "json",
+      "loglevel",
+      "retrievetargetdir",
+      "targetusername",
+      "unzip",
+      "verbose",
+      "wait",
+      "zipfilename"
+    ]
+  },
   {
     "command": "force:mdapi:describemetadata",
     "plugin": "@salesforce/plugin-source",

diff --git a/messages/deploy.json b/messages/deploy.json
@@ -74,12 +74,11 @@
     ]
   },
   "checkOnlySuccess": "Successfully validated the deployment. %s components deployed and %s tests run.\nUse the --verbose parameter to see detailed output.",
-  "MissingDeployId": "No deploy ID was provided or found in deploy history",
-  "InvalidStashFile": "Invalid deployment stash file encountered. File has been renamed to: %s.  Please specify a deploy ID using the command parameter.",
-  "deployCanceled": "The deployment has been canceled by %s",
+  "MissingDeployId": "No deploy ID was provided or found in deploy history.",
+  "deployCanceled": "The deployment has been canceled by %s.",
   "deployFailed": "Deploy failed.",
   "asyncDeployQueued": "Deploy has been queued.",
   "asyncDeployCancel": "Run sfdx force:source:deploy:cancel -i %s to cancel the deploy.",
   "asyncDeployReport": "Run sfdx force:source:deploy:report -i %s to get the latest status.",
-  "invalidDeployId": "The provided ID is invalid, deploy IDs must start with '0Af'"
+  "invalidDeployId": "The provided ID is invalid, deploy IDs must start with '0Af'."
 }
diff --git a/messages/md.retrieve.json b/messages/md.retrieve.json
@@ -0,0 +1,56 @@
+{
+  "retrieveCmd": {
+    "description": "retrieve metadata from an org using Metadata API\nUses Metadata API to retrieve a .zip of XML files that represent metadata from the targeted org. The default target username is the admin user for the default scratch org. You can retrieve and deploy up to 10,000 files or 400 MB (39 MB compressed) at one time.",
+    "examples": [
+      "Retrieve metadata in the default project directory into the target directory:",
+      "  sfdx force:mdapi:beta:retrieve -r path/to/retrieve/dir",
+      "Retrieve metadata defined in the specified manifest into the target directory:",
+      "  sfdx force:mdapi:beta:retrieve -r path/to/retrieve/dir -k package.xml",
+      "Retrieve metadata defined by the specified directory, name the retrieved zipfile and extract all contents",
+      "  sfdx force:mdapi:beta:retrieve -d path/to/apexClasses -r path/to/retrieve/dir --unzip --zipfilename apexClasses.zip",
+      "Enqueue a retrieve request but do not wait for the metadata to be retrieved:",
+      "  sfdx force:mdapi:beta:retrieve -r path/to/retrieve/dir --wait 0"
+    ]
+  },
+  "reportCmd": {
+    "description": "check the status of a metadata retrieval\nSpecify the job ID and a target directory for the retrieve you want to check. You can also specify a wait time (minutes) to check for updates to the retrieve status. If the retrieve was successful, the resulting zip file will be saved to the location passed in with the retrieve target parameter.",
+    "examples": [
+      "Poll until the metadata is retrieved (or timeout is reached) using data from the last force:mdapi:retrieve command:",
+      "  sfdx force:mdapi:beta:retrieve:report",
+      "Report the current status of the last retrieve command. If the retrieve is complete the zip file of metadata is written to the target directoy:",
+      "  sfdx force:mdapi:beta:retrieve:report -r path/to/retrieve/dir -w 0",
+      "Poll until the metadata is retrieved (or timeout is reached) using the provided RetrieveID, naming the zip file and extracting all contents:",
+      "  sfdx force:mdapi:beta:retrieve:report -i retrieveId -r path/to/retrieve/dir --unzip --zipfilename apexClasses.zip"
+    ]
+  },
+  "flags": {
+    "retrievetargetdir": "directory root for the retrieved files",
+    "unpackaged": "file path of manifest of components to retrieve",
+    "sourcedir": "source dir to use instead of the default package dir in sfdx-project.json",
+    "packagenames": "a comma-separated list of packages to retrieve",
+    "singlepackage": "indicates that the zip file points to a directory structure for a single package",
+    "zipfilename": "file name to use for the retrieved zip file",
+    "unzip": "extract all files from the retrieved zip file",
+    "wait": "wait time for command to finish in minutes",
+    "apiversion": "target API version for the retrieve",
+    "verbose": "verbose output of retrieve result",
+    "jobid": "job ID of the retrieve you want to check; defaults to your most recent CLI retrieval if not specified"
+  },
+  "flagsLong": {
+    "retrievetargetdir": "The root of the directory structure where the retrieved .zip or metadata files are put.",
+    "unpackaged": "The complete path for the manifest file that specifies the components to retrieve.",
+    "sourcedir": "The source directory to use instead of the default package directory specified in sfdx-project.json",
+    "packagenames": "A comma-separated list of package names to retrieve.",
+    "singlepackage": "Indicates that the specified .zip file points to a directory structure for a single package. By default, the CLI assumes the directory is structured for a set of packages.",
+    "zipfilename": "The file name to use for the retrieved zip file.",
+    "unzip": "Extract all files from the retrieved zip file.",
+    "wait": "The number of minutes to wait for the command to complete.",
+    "apiversion": "Use to override the default, which is the latest version supported by your CLI plug-in, with the version in your package.xml file.",
+    "verbose": "Indicates that you want verbose output from the retrieve operation.",
+    "jobid": "The job ID (asyncId) of the retrieve you want to check. If not specified, the default value is the ID of the most recent metadata retrieval you ran using Salesforce CLI. You must specify a --retrievetargetdir. Use with --wait to resume waiting."
+  },
+  "InvalidFlagPath": "The %s command parameter specifies an invalid path: %s\n%s",
+  "InvalidPackageNames": "You specified [%s]. Try again and specify only one package when using --singlepackage.",
+  "MissingRetrieveId": "The jobid command parameter was not provided, neither directly nor from a previous retrieval.",
+  "checkStatus": "To check the status of this retrieve, run \"sfdx force:mdapi:beta:retrieve:report %s\".\nIf the retrieve request has completed, the retrieved metadata zip file will be written to the retrieve target dir."
+}
diff --git a/messages/retrieve.json b/messages/retrieve.json
@@ -47,10 +47,5 @@
   "columnNumberColumn": "COLUMN NUMBER",
   "lineNumberColumn": "LINE NUMBER",
   "errorColumn": "PROBLEM",
-  "wantsToRetrieveCustomFields": "Because you're retrieving one or more CustomFields, we're also retrieving the CustomObject to which it's associated.",
-  "spinnerMessages": {
-    "componentSetBuild": "Preparing retrieve request",
-    "sendingRequest": "Sending request to org (metadata API version %s)",
-    "polling": "Waiting for the org to respond"
-  }
+  "wantsToRetrieveCustomFields": "Because you're retrieving one or more CustomFields, we're also retrieving the CustomObject to which it's associated."
 }
diff --git a/messages/spinner.json b/messages/spinner.json
@@ -0,0 +1,8 @@
+{
+  "retrieve": {
+    "main": "Retrieving metadata from %s",
+    "componentSetBuild": "Preparing retrieve request",
+    "sendingRequest": "Sending request to org (metadata API version %s)",
+    "polling": "Waiting for the org to respond"
+  }
+}
diff --git a/messages/stash.json b/messages/stash.json
@@ -0,0 +1,4 @@
+{
+  "InvalidStashKey": "The stash key provided is invalid.  Found: [%s].",
+  "InvalidStashFile": "Invalid stash file encountered. File has been renamed to: %s.  Please re-run the command providing the --jobid parameter."
+}
diff --git a/package.json b/package.json
@@ -126,6 +126,9 @@
                 "subtopics": {
                   "deploy": {
                     "description": "new versions of deploy report command"
+                  },
+                  "retrieve": {
+                    "description": "new versions of retrieve report command"
                   }
                 }
               }